【Android Developers Training】 101. 显示快速联系人挂件（Quick Contact Badge）
注：本文翻译自Google官方的Android Developers Training文档，译者技术一般，由于喜爱安卓而产生了翻译的念头，纯属个人兴趣爱好。
原文链接：http://developer.android.com/training/contacts-provider/display-contact-badge.html
这节课将会向你展示如何添加一个QuickContactBadge到你的UI中，以及如何将数据和它捆绑起来。一个QuickContactBadge是一个显示缩略图的空间。虽然你可以使用Bitmap显示任何缩略图，但是你必须要将联系人照片进行解码。
缩略图的作用类似于一个控制器：当用户点击缩略图时，QuickContactBadge会扩展成一个对话框，其中包含如下内容：
一个放大的图标
一个和该联系人关联的大图标，如果没有的话，就用一个默认的占位图片代替。
应用图标
每一个具体的联系人信息旁会有一个应用图标，它说明该数据可被此内置应用处理。例如，如果联系人的数据中有一个或多个email地址，那么就会出现一个email的图标。当用户点击这个图标，联系人的所有email地址会显示出来，之后用户如果点击了某一个email地址，会打开电子邮件应用，其中的收件人地址就是所选中的email地址。
QuickContactBadge提供了一个指向联系人详细信息的即时访问，以及一个和联系人沟通的快速渠道。用户不需要查询联系人列表，寻找并拷贝信息，之后再把它粘贴到其它的应用界面中去。取而代之的，它们只需要在QuickContactBadge上进行点击，选择他们想要使用的沟通方式，并直接通过相关的应用发送消息即可。
一）. 添加一个QuickContactBadge视图
要添加一个QuickContactBadge，在你的布局中插入一个<QuickContactBadge>元素，例如：
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="match_parent"> ... <QuickContactBadge android:id=@+id/quickbadge android:layout_height="wrap_content" android:layout_width="wrap_content" android:scaleType="centerCrop"/> ... </RelativeLayout>
二）. 检索提供器的数据
要在QuickContactBadge中显示一个联系人，你需要一个联系人的内容URI还有缩略图的Bitmap对象。你从Contacts Provider搜索的列数据用来创建内容URI和Bitmap对象。指定这些列左右你在Cursor中用来加载数据的投影的一部分。
对Android 3.0（API版本11）及之后的版本，在你的投影中包含下面几列：
对Android 2.3.3（API版本10）及之前的版本，在你的投影中包含下面几列：
我们假设在这节课之前，你已经加载了一个Cursor，它包含了上面的这些列，还有一些你已经选择了的列。要学习如何使用Cursor检索这些列数据，可以参阅：Retrieving a List of Contacts（博客链接：http://www.cnblogs.com/jdneo/p/3674830.html）
三）. 设置内容URI和缩略图
一旦你有了必要的列，你就可以将数据绑定到QuickContactBadge上。
设置内容URI
要为联系人的内容URI，调用getLookupUri(id,lookupKey)来获取一个CONTENT_LOOKUP_URI，然后调用assignContactUri()来设置联系人。例如：
// The Cursor that contains contact rows Cursor mCursor; // The index of the _ID column in the Cursor int mIdColumn; // The index of the LOOKUP_KEY column in the Cursor int mLookupKeyColumn; // A content URI for the desired contact Uri mContactUri; // A handle to the QuickContactBadge view QuickContactBadge mBadge; ... mBadge = (QuickContactBadge) findViewById(R.id.quickbadge); /* * Insert code here to move to the desired cursor row */ // Gets the _ID column index mIdColumn = mCursor.getColumnIndex(Contacts._ID); // Gets the LOOKUP_KEY index mLookupKeyColumn = mCursor.getColumnIndex(Contacts.LOOKUP_KEY); // Gets a content URI for the contact mContactUri = Contacts.getLookupUri( mCursor.getLong(mIdColumn), mCursor.getString(mLookupKeyColumn) ); mBadge.assignContactUri(mContactUri);
当用户点击了QuickContactBadge图标后，联系人的详细信息会自动显示在对话框中。
设置照片缩略图
为QuickContactBadge设置联系人的URI并不会自动的加载他的照片。要加载照片，需要从联系人的Cursor行中获取照片的URI，使用它来打开包含有压缩后的照片缩略图文件，并将该文件读入一个Bitmap对象。
Note：
PHOTO_THUMBNAIL_URI列在Android 3.0之前的版本中是没有的。对于那些较早的版本，你必须从Contacts.Photo自表中获取URI。
首先，为访问包含有Contacts._ID和Contacts.LOOKUP_KEY列的Cursor设置变量，如下所示：
// The column in which to find the thumbnail ID int mThumbnailColumn; /* * The thumbnail URI, expressed as a String. * Contacts Provider stores URIs as String values. */ String mThumbnailUri; ... /* * Gets the photo thumbnail column index if * platform version >= Honeycomb */ if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) { mThumbnailColumn = mCursor.getColumnIndex(Contacts.PHOTO_THUMBNAIL_URI); // Otherwise, sets the thumbnail column to the _ID column } else { mThumbnailColumn = mIdColumn; } /* * Assuming the current Cursor position is the contact you want, * gets the thumbnail ID */ mThumbnailUri = mCursor.getString(mThumbnailColumn); ...
定义一个方法，它获取联系人的照片数据，以及缩略图的目标大小，并将照片以一个适当尺寸的Bitmap形式返回。我们首先从构造一个指向该缩略图的URI开始：
/** * Load a contact photo thumbnail and return it as a Bitmap, * resizing the image to the provided image dimensions as needed. * @param photoData photo ID Prior to Honeycomb, the contact's _ID value. * For Honeycomb and later, the value of PHOTO_THUMBNAIL_URI. * @return A thumbnail Bitmap, sized to the provided width and height. * Returns null if the thumbnail is not found. */ private Bitmap loadContactPhotoThumbnail(String photoData) { // Creates an asset file descriptor for the thumbnail file. AssetFileDescriptor afd = null; // try-catch block for file not found try { // Creates a holder for the URI. Uri thumbUri; // If Android 3.0 or later if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) { // Sets the URI from the incoming PHOTO_THUMBNAIL_URI thumbUri = Uri.parse(photoData); } else { // Prior to Android 3.0, constructs a photo Uri using _ID /* * Creates a contact URI from the Contacts content URI * incoming photoData (_ID) */ final Uri contactUri = Uri.withAppendedPath( Contacts.CONTENT_URI, photoData); /* * Creates a photo URI by appending the content URI of * Contacts.Photo. */ thumbUri = Uri.withAppendedPath( contactUri, Photo.CONTENT_DIRECTORY); } /* * Retrieves an AssetFileDescriptor object for the thumbnail * URI * using ContentResolver.openAssetFileDescriptor */ afd = getActivity().getContentResolver(). openAssetFileDescriptor(thumbUri, "r"); /* * Gets a file descriptor from the asset file descriptor. * This object can be used across processes. */ FileDescriptor fileDescriptor = afd.getFileDescriptor(); // Decode the photo file and return the result as a Bitmap // If the file descriptor is valid if (fileDescriptor != null) { // Decodes the bitmap return BitmapFactory.decodeFileDescriptor( fileDescriptor, null, null); } // If the file isn't found } catch (FileNotFoundException e) { /* * Handle file not found errors */ } // In all cases, close the asset file descriptor } finally { if (afd != null) { try { afd.close(); } catch (IOException e) {} } } return null; }
在你的代码中调用loadContactPhotoThumbnail()来获取缩略图的Bitmap对象，将结果用来设置你的QuickContactBadge中的联系人缩略图：
... /* * Decodes the thumbnail file to a Bitmap. */ Bitmap mThumbnail = loadContactPhotoThumbnail(mThumbnailUri); /* * Sets the image in the QuickContactBadge * QuickContactBadge inherits from ImageView, so */ mBadge.setImageBitmap(mThumbnail);
三）. 添加一个QuickContactBadge到ListView中
一个QuickContactBadge是一个ListView的非常有用的控件，它会显示联系人的列表。使用QuickContactBadge为每一个联系人显示他的缩略图；当用户点击缩略图后，QuickContactBadge对话框会出现。
添加QuickContactBadge元素
首先，添加一个QuickContactBadge视图元素到你的列表项布局中。例如，如果你想要显示一个QuickContactBadge还有你检索的每个联系人的名字，将下列XML放置到一个布局文件中：
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="wrap_content"> <QuickContactBadge android:id="@+id/quickcontact" android:layout_height="wrap_content" android:layout_width="wrap_content" android:scaleType="centerCrop"/> <TextView android:id="@+id/displayname" android:layout_width="match_parent" android:layout_height="wrap_content" android:layout_toRightOf="@+id/quickcontact" android:gravity="center_vertical" android:layout_alignParentRight="true" android:layout_alignParentTop="true"/> </RelativeLayout>
在下面的章节中，这一文件我们称它为：contact_item_layout.xml。
配置一个自定义CursorAdapter
要将一个CursorAdapter绑定到一个包含有QuickContactBadge的ListView上，自定义一个自定义的适配器，它继承自CursorAdapter。这一方法允许你在将Cursor绑定到QuickContactBadge之前，可以在Cursor内处理数据。同时这个方法还允许你将多个Cursor列绑定到QuickContactBadge上。这些方法对于一个传统的CursorAdapter而言是不可能做到的。
对于CursorAdapter的子类，你必须覆写下列方法：
填充一个新的View对象来显示列表项布局。在该方法的覆写版本中，保存布局中子View对象的句柄，包括子QuickContactBadge。通过使用这一方法，你可以避免每次你填充一个新的布局时去获取子View对象的句柄。
你必须要覆写这一方法，这样你才能获取每个自View对象的句柄。这一方法允许你在CursorAdapter.bindView()方法中控制他们的捆绑关系。
将数据从当前的Cursor行移动到列表项布局中子View对象里。你必须覆写这一方法这样你就能同时将联系人URI和缩略图捆绑到QuickContactBadge上。而默认的实现值允许一列数据和一个View间一对一的对应关系。
下面的代码片段包含了自定义子类CursorAdapter的一个例子：
定义自定义列表适配器
定义CursorAdapter的子类，包括它的构造函数，覆写newView()和bindView()：
/** * * */ private class ContactsAdapter extends CursorAdapter { private LayoutInflater mInflater; ... public ContactsAdapter(Context context) { super(context, null, 0); /* * Gets an inflater that can instantiate * the ListView layout from the file. */ mInflater = LayoutInflater.from(context); ... } ... /** * Defines a class that hold resource IDs of each item layout * row to prevent having to look them up each time data is * bound to a row. */ private class ViewHolder { TextView displayname; QuickContactBadge quickcontact; } .. @Override public View newView( Context context, Cursor cursor, ViewGroup viewGroup) { /* Inflates the item layout. Stores resource IDs in a * in a ViewHolder class to prevent having to look * them up each time bindView() is called. */ final View itemView = mInflater.inflate( R.layout.contact_list_layout, viewGroup, false ); final ViewHolder holder = new ViewHolder(); holder.displayname = (TextView) view.findViewById(R.id.displayname); holder.quickcontact = (QuickContactBadge) view.findViewById(R.id.quickcontact); view.setTag(holder); return view; } ... @Override public void bindView( View view, Context context, Cursor cursor) { final ViewHolder holder = (ViewHolder) view.getTag(); final String photoData = cursor.getString(mPhotoDataIndex); final String displayName = cursor.getString(mDisplayNameIndex); ... // Sets the display name in the layout holder.displayname = cursor.getString(mDisplayNameIndex); ... /* * Generates a contact URI for the QuickContactBadge. */ final Uri contactUri = Contacts.getLookupUri( cursor.getLong(mIdIndex), cursor.getString(mLookupKeyIndex)); holder.quickcontact.assignContactUri(contactUri); String photoData = cursor.getString(mPhotoDataIndex); /* * Decodes the thumbnail file to a Bitmap. * The method loadContactPhotoThumbnail() is defined * in the section "Set the Contact URI and Thumbnail" */ Bitmap thumbnailBitmap = loadContactPhotoThumbnail(photoData); /* * Sets the image in the QuickContactBadge * QuickContactBadge inherits from ImageView */ holder.quickcontact.setImageBitmap(thumbnailBitmap); }
设置变量
在你的代码中，设置变量，包括一个Cursor投影，它包含了必要的那些列。
Note：
下面的代码片段使用了loadContactPhotoThumbnail()方法，这在之前的章节中该方法已经详细叙述过了。
例如：
public class ContactsFragment extends Fragment implements LoaderManager.LoaderCallbacks<Cursor> { ... // Defines a ListView private ListView mListView; // Defines a ContactsAdapter private ContactsAdapter mAdapter; ... // Defines a Cursor to contain the retrieved data private Cursor mCursor; /* * Defines a projection based on platform version. This ensures * that you retrieve the correct columns. */ private static final String[] PROJECTION = { Contacts._ID, Contacts.LOOKUP_KEY, (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) ? Contacts.DISPLAY_NAME_PRIMARY : Contacts.DISPLAY_NAME (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) ? Contacts.PHOTO_THUMBNAIL_ID : /* * Although it's not necessary to include the * column twice, this keeps the number of * columns the same regardless of version */ Contacts_ID ... }; /* * As a shortcut, defines constants for the * column indexes in the Cursor. The index is * 0-based and always matches the column order * in the projection. */ // Column index of the _ID column private int mIdIndex = 0; // Column index of the LOOKUP_KEY column private int mLookupKeyIndex = 1; // Column index of the display name column private int mDisplayNameIndex = 3; /* * Column index of the photo data column. * It's PHOTO_THUMBNAIL_URI for Honeycomb and later, * and _ID for previous versions. */ private int mPhotoDataIndex = Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB ? 3 : 0; ...
设置ListView
在Fragment.onCreate()中，实例化自定义的cursor适配器，并获得一个ListView的句柄：
@Override public void onCreate(Bundle savedInstanceState) { ... /* * Instantiates the subclass of * CursorAdapter */ ContactsAdapter mContactsAdapter = new ContactsAdapter(getActivity()); /* * Gets a handle to the ListView in the file * contact_list_layout.xml */ mListView = (ListView) findViewById(R.layout.contact_list_layout); ... } ...
在onActivityCreated()中，将ContactsAdapter和ListView绑定起来：
@Override public void onActivityCreated(Bundle savedInstanceState) { ... // Sets up the adapter for the ListView mListView.setAdapter(mAdapter); ... } ...
当你获取了一个包含有联系人数据的Cursor，通常是在onLoadFinished()，调用swapCursor()将Cursor数据移动到ListView。这会为联系人列表中的每一个条目显示QuickContactBadge：
public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) { // When the loader has completed, swap the cursor into the adapter. mContactsAdapter.swapCursor(cursor); }
当你通过一个CursorAdapter（或它的子类）将一个Cursor绑定到ListView上，并且你使用CursorLoader加载Cursor，一定要记得在onLoaderReset()的实现中清楚Cursor的引用，例如：
@Override public void onLoaderReset(Loader<Cursor> loader) { // Removes remaining reference to the previous Cursor mContactsAdapter.swapCursor(null); }
