【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）及之后的版本，在你的投影中包含下面几列：

• Contacts._ID

• Contacts.LOOKUP_KEY

• Contacts.PHOTO_THUMBNAIL_URI


对Android 2.3.3（API版本10）及之前的版本，在你的投影中包含下面几列：

• Contacts._ID

• Contacts.LOOKUP_KEY


我们假设在这节课之前，你已经加载了一个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的子类，你必须覆写下列方法：

CursorAdapter.newView()

填充一个新的View对象来显示列表项布局。在该方法的覆写版本中，保存布局中子View对象的句柄，包括子QuickContactBadge。通过使用这一方法，你可以避免每次你填充一个新的布局时去获取子View对象的句柄。

你必须要覆写这一方法，这样你才能获取每个自View对象的句柄。这一方法允许你在CursorAdapter.bindView()方法中控制他们的捆绑关系。

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);
    }