检索联系人列表

本课程向您展示如何使用以下技术检索与搜索字符串的全部或部分匹配的联系人列表

匹配联系人姓名

通过将搜索字符串与联系人姓名数据的全部或部分进行匹配来检索联系人列表。联系人提供程序允许出现相同名称的多个实例，因此此技术可以返回匹配项列表。

匹配特定类型的数据，例如电话号码

通过将搜索字符串与特定类型的详细信息数据（例如电子邮件地址）进行匹配来检索联系人列表。例如，此技术允许您列出所有电子邮件地址与搜索字符串匹配的联系人。

匹配任何类型的数据

通过将搜索字符串与任何类型的详细信息数据进行匹配来检索联系人列表，包括姓名、电话号码、街道地址、电子邮件地址等等。例如，此技术允许您为搜索字符串接受任何类型的数据，然后列出数据与字符串匹配的联系人。

注意： 本课程中的所有示例都使用 CursorLoader 从联系人提供程序检索数据。 CursorLoader 在与 UI 线程分离的线程上运行其查询。这确保了查询不会减慢 UI 响应时间并导致糟糕的用户体验。有关更多信息，请参阅 Android 培训课程 在后台加载数据.

请求读取提供程序的权限

要对联系人提供程序执行任何类型的搜索，您的应用程序必须具有 READ_CONTACTS 权限。要请求此权限，请将此 <uses-permission> 元素添加到您的清单文件作为 <manifest> 的子元素

    <uses-permission android:name="android.permission.READ_CONTACTS" />

按姓名匹配联系人并列出结果

此技术尝试将搜索字符串与联系人提供程序的 ContactsContract.Contacts 表中的联系人姓名进行匹配。您通常希望在 ListView 中显示结果，以便用户可以在匹配的联系人中进行选择。

定义 ListView 和项目布局

要在 ListView 中显示搜索结果，您需要一个主布局文件来定义整个 UI（包括 ListView），以及一个项目布局文件来定义 ListView 的一行。例如，您可以创建主布局文件 res/layout/contacts_list_view.xml，其中包含以下 XML

<?xml version="1.0" encoding="utf-8"?>
<ListView xmlns:android="http://schemas.android.com/apk/res/android"
          android:id="@android:id/list"
          android:layout_width="match_parent"
          android:layout_height="match_parent"/>

此 XML 使用内置的 Android ListView 小部件 android:id/list。

使用以下 XML 定义项目布局文件 contacts_list_item.xml

<?xml version="1.0" encoding="utf-8"?>
<TextView xmlns:android="http://schemas.android.com/apk/res/android"
          android:id="@android:id/text1"
          android:layout_width="match_parent"
          android:layout_height="wrap_content"
          android:clickable="true"/>

此 XML 使用内置的 Android TextView 小部件 android:text1。

注意： 本课程不描述从用户那里获取搜索字符串的 UI，因为您可能希望间接获取字符串。例如，您可以为用户提供一个选项，以搜索姓名与传入文本消息中的字符串匹配的联系人。

您编写的两个布局文件定义了一个显示 ListView 的用户界面。下一步是编写使用此 UI 来显示联系人列表的代码。

定义一个显示联系人列表的 Fragment

要显示联系人列表，首先要定义一个由 Activity 加载的 Fragment。使用 Fragment 是一种更灵活的技术，因为您可以使用一个 Fragment 来显示列表，并使用第二个 Fragment 来显示用户从列表中选择的联系人的详细信息。使用这种方法，您可以将本课程中介绍的一种技术与 检索联系人的详细信息 课程中的一种技术结合起来。

要了解如何从 Activity 中使用一个或多个 Fragment 对象，请阅读培训课程 使用 Fragment 构建动态 UI。

为了帮助您编写针对联系人提供者的查询，Android 框架提供了一个名为 ContactsContract 的合约类，该类定义了用于访问提供者的有用常量和方法。当您使用此类时，您不必为内容 URI、表名或列定义自己的常量。要使用此类，请包含以下语句

import android.provider.ContactsContract

import android.provider.ContactsContract;

由于代码使用 CursorLoader 从提供者检索数据，因此您必须指定它实现了加载器接口 LoaderManager.LoaderCallbacks。此外，为了帮助检测用户从搜索结果列表中选择了哪个联系人，请实现适配器接口 AdapterView.OnItemClickListener。例如

...
import android.support.v4.app.Fragment
import android.support.v4.app.LoaderManager
import android.widget.AdapterView
...
class ContactsFragment :
        Fragment(),
        LoaderManager.LoaderCallbacks<Cursor>,
        AdapterView.OnItemClickListener {

...
import android.support.v4.app.Fragment;
import android.support.v4.app.LoaderManager.LoaderCallbacks;
import android.widget.AdapterView;
...
public class ContactsFragment extends Fragment implements
        LoaderManager.LoaderCallbacks<Cursor>,
        AdapterView.OnItemClickListener {

定义全局变量

定义在代码的其他部分中使用的全局变量

...
/*
 * Defines an array that contains column names to move from
 * the Cursor to the ListView.
 */
@SuppressLint("InlinedApi")
private val FROM_COLUMNS: Array<String> = arrayOf(
        if ((Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB)) {
            ContactsContract.Contacts.DISPLAY_NAME_PRIMARY
        } else {
            ContactsContract.Contacts.DISPLAY_NAME
        }
)
/*
 * Defines an array that contains resource ids for the layout views
 * that get the Cursor column contents. The id is pre-defined in
 * the Android framework, so it is prefaced with "android.R.id"
 */
private val TO_IDS: IntArray = intArrayOf(android.R.id.text1)
...
class ContactsFragment :
        Fragment(),
        LoaderManager.LoaderCallbacks<Cursor>,
        AdapterView.OnItemClickListener {
    ...
    // Define global mutable variables
    // Define a ListView object
    lateinit var contactsList: ListView
    // Define variables for the contact the user selects
    // The contact's _ID value
    var contactId: Long = 0
    // The contact's LOOKUP_KEY
    var contactKey: String? = null
    // A content URI for the selected contact
    var contactUri: Uri? = null
    // An adapter that binds the result Cursor to the ListView
    private val cursorAdapter: SimpleCursorAdapter? = null

    ...
    /*
     * Defines an array that contains column names to move from
     * the Cursor to the ListView.
     */
    @SuppressLint("InlinedApi")
    private final static String[] FROM_COLUMNS = {
            Build.VERSION.SDK_INT
                    >= Build.VERSION_CODES.HONEYCOMB ?
                    ContactsContract.Contacts.DISPLAY_NAME_PRIMARY :
                    ContactsContract.Contacts.DISPLAY_NAME
    };
    /*
     * Defines an array that contains resource ids for the layout views
     * that get the Cursor column contents. The id is pre-defined in
     * the Android framework, so it is prefaced with "android.R.id"
     */
    private final static int[] TO_IDS = {
           android.R.id.text1
    };
    // Define global mutable variables
    // Define a ListView object
    ListView contactsList;
    // Define variables for the contact the user selects
    // The contact's _ID value
    long contactId;
    // The contact's LOOKUP_KEY
    String contactKey;
    // A content URI for the selected contact
    Uri contactUri;
    // An adapter that binds the result Cursor to the ListView
    private SimpleCursorAdapter cursorAdapter;
    ...

注意：由于 Contacts.DISPLAY_NAME_PRIMARY 需要 Android 3.0（API 版本 11）或更高版本，因此将应用程序的 minSdkVersion 设置为 10 或更低版本会在 Android Studio 中生成 Android Lint 警告。要关闭此警告，请在 FROM_COLUMNS 的定义之前添加注释 @SuppressLint("InlinedApi")。

初始化 Fragment

初始化 Fragment。添加 Android 系统所需的空公共构造函数，并在回调方法 onCreateView() 中膨胀 Fragment 对象的 UI。例如

    // A UI Fragment must inflate its View
    override fun onCreateView(
            inflater: LayoutInflater,
            container: ViewGroup?,
            savedInstanceState: Bundle?
    ): View? {
        // Inflate the fragment layout
        return inflater.inflate(R.layout.contact_list_fragment, container, false)
    }

    // Empty public constructor, required by the system
    public ContactsFragment() {}

    // A UI Fragment must inflate its View
    @Override
    public View onCreateView(LayoutInflater inflater, ViewGroup container,
            Bundle savedInstanceState) {
        // Inflate the fragment layout
        return inflater.inflate(R.layout.contact_list_fragment,
            container, false);
    }

为 ListView 设置 CursorAdapter

设置 SimpleCursorAdapter，将搜索结果绑定到 ListView。要获取显示联系人的 ListView 对象，您需要使用 Fragment 的父活动调用 Activity.findViewById()。当您调用 setAdapter() 时，请使用父活动的 Context。例如

    override fun onActivityCreated(savedInstanceState: Bundle?) {
        super.onActivityCreated(savedInstanceState)
        ...
        // Gets the ListView from the View list of the parent activity
        activity?.also {
            contactsList = it.findViewById<ListView>(R.id.contact_list_view)
            // Gets a CursorAdapter
            cursorAdapter = SimpleCursorAdapter(
                    it,
                    R.layout.contact_list_item,
                    null,
                    FROM_COLUMNS, TO_IDS,
                    0
            )
            // Sets the adapter for the ListView
            contactsList.adapter = cursorAdapter
        }
    }

    public void onActivityCreated(Bundle savedInstanceState) {
        super.onActivityCreated(savedInstanceState);
        ...
        // Gets the ListView from the View list of the parent activity
        contactsList =
            (ListView) getActivity().findViewById(R.layout.contact_list_view);
        // Gets a CursorAdapter
        cursorAdapter = new SimpleCursorAdapter(
                getActivity(),
                R.layout.contact_list_item,
                null,
                FROM_COLUMNS, TO_IDS,
                0);
        // Sets the adapter for the ListView
        contactsList.setAdapter(cursorAdapter);
    }

设置所选联系人的监听器

当您显示搜索结果时，您通常希望允许用户选择单个联系人以进行进一步处理。例如，当用户点击联系人时，您可以在地图上显示该联系人的地址。要提供此功能，您首先通过指定该类实现了 AdapterView.OnItemClickListener，将当前 Fragment 定义为点击监听器，如 定义显示联系人列表的 Fragment 部分所示。

要继续设置监听器，请通过在 onActivityCreated() 中调用方法 setOnItemClickListener()，将其绑定到 ListView。例如

    fun onActivityCreated(savedInstanceState:Bundle) {
        ...
        // Set the item click listener to be the current fragment.
        contactsList.onItemClickListener = this
        ...
    }

    public void onActivityCreated(Bundle savedInstanceState) {
        ...
        // Set the item click listener to be the current fragment.
        contactsList.setOnItemClickListener(this);
        ...
    }

由于您指定了当前 Fragment 是 ListView 的 OnItemClickListener，因此您现在需要实现其必需的方法 onItemClick()，该方法处理点击事件。这将在后面的部分中介绍。

定义投影

定义一个常量，其中包含您要从查询中返回的列。ListView 中的每个项目都显示联系人的显示名称，其中包含联系人的姓名主要形式。在 Android 3.0（API 版本 11）及更高版本中，此列的名称为 Contacts.DISPLAY_NAME_PRIMARY；在之前的版本中，其名称为 Contacts.DISPLAY_NAME。

列 Contacts._ID 由 SimpleCursorAdapter 绑定过程使用。Contacts._ID 和 LOOKUP_KEY 一起使用，用于为用户选择的联系人构建内容 URI。

...
@SuppressLint("InlinedApi")
private val PROJECTION: Array<out String> = arrayOf(
        ContactsContract.Contacts._ID,
        ContactsContract.Contacts.LOOKUP_KEY,
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB)
            ContactsContract.Contacts.DISPLAY_NAME_PRIMARY
        else
            ContactsContract.Contacts.DISPLAY_NAME
)

...
@SuppressLint("InlinedApi")
private static final String[] PROJECTION =
        {
            Contacts._ID,
            Contacts.LOOKUP_KEY,
            Build.VERSION.SDK_INT
                    >= Build.VERSION_CODES.HONEYCOMB ?
                    ContactsContract.Contacts.DISPLAY_NAME_PRIMARY :
                    ContactsContract.Contacts.DISPLAY_NAME

        };

为 Cursor 列索引定义常量

要从 Cursor 中的单个列获取数据，您需要该列在 Cursor 中的索引。您可以为 Cursor 列的索引定义常量，因为索引与投影中列名称的顺序相同。例如

// The column index for the _ID column
private const val CONTACT_ID_INDEX: Int = 0
// The column index for the CONTACT_KEY column
private const val CONTACT_KEY_INDEX: Int = 1

// The column index for the _ID column
private static final int CONTACT_ID_INDEX = 0;
// The column index for the CONTACT_KEY column
private static final int CONTACT_KEY_INDEX = 1;

指定选择条件

要指定您想要的数据，请创建文本表达式和变量的组合，这些表达式和变量告诉提供者要搜索的数据列以及要查找的值。

对于文本表达式，请定义一个常量，其中列出了搜索列。虽然此表达式也可以包含值，但首选做法是使用“？”占位符来表示值。在检索期间，占位符将被数组中的值替换。使用“？”作为占位符可确保搜索规范是通过绑定而不是通过 SQL 编译生成的。这种做法消除了恶意 SQL 注入的可能性。例如

// Defines the text expression
@SuppressLint("InlinedApi")
private val SELECTION: String =
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB)
            "${ContactsContract.Contacts.DISPLAY_NAME_PRIMARY} LIKE ?"
        else
            "${ContactsContract.Contacts.DISPLAY_NAME} LIKE ?"
...
    // Defines a variable for the search string
    private val searchString: String = ...
    // Defines the array to hold values that replace the ?
    private val selectionArgs = arrayOf<String>(searchString)

    // Defines the text expression
    @SuppressLint("InlinedApi")
    private static final String SELECTION =
            Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB ?
            Contacts.DISPLAY_NAME_PRIMARY + " LIKE ?" :
            Contacts.DISPLAY_NAME + " LIKE ?";
    // Defines a variable for the search string
    private String searchString;
    // Defines the array to hold values that replace the ?
    private String[] selectionArgs = { searchString };

定义 onItemClick() 方法

在上一节中，您为 ListView 设置了项目点击监听器。现在，通过定义方法 AdapterView.OnItemClickListener.onItemClick() 来实现监听器的操作

    override fun onItemClick(parent: AdapterView<*>, view: View?, position: Int, id: Long) {
        // Get the Cursor
        val cursor: Cursor? = (parent.adapter as? CursorAdapter)?.cursor?.apply {
            // Move to the selected contact
            moveToPosition(position)
            // Get the _ID value
            contactId = getLong(CONTACT_ID_INDEX)
            // Get the selected LOOKUP KEY
            contactKey = getString(CONTACT_KEY_INDEX)
            // Create the contact's content Uri
            contactUri = ContactsContract.Contacts.getLookupUri(contactId, mContactKey)
            /*
             * You can use contactUri as the content URI for retrieving
             * the details for a contact.
             */
        }
    }

    @Override
    public void onItemClick(
        AdapterView<?> parent, View item, int position, long rowID) {
        // Get the Cursor
        Cursor cursor = parent.getAdapter().getCursor();
        // Move to the selected contact
        cursor.moveToPosition(position);
        // Get the _ID value
        contactId = cursor.getLong(CONTACT_ID_INDEX);
        // Get the selected LOOKUP KEY
        contactKey = cursor.getString(CONTACT_KEY_INDEX);
        // Create the contact's content Uri
        contactUri = Contacts.getLookupUri(contactId, mContactKey);
        /*
         * You can use contactUri as the content URI for retrieving
         * the details for a contact.
         */
    }

初始化加载器

由于您使用 CursorLoader 来检索数据，因此您必须初始化后台线程和其他控制异步检索的变量。如以下示例所示，在 onCreate() 中进行初始化

class ContactsFragment :
        Fragment(),
        LoaderManager.LoaderCallbacks<Cursor> {
    ...
    override fun onCreate(savedInstanceState: Bundle?) {
        // Always call the super method first
        super.onCreate(savedInstanceState)
        ...
        // Initializes the loader
        loaderManager.initLoader(0, null, this)

public class ContactsFragment extends Fragment implements
        LoaderManager.LoaderCallbacks<Cursor> {
    ...
    // Called just before the Fragment displays its UI
    @Override
    public void onCreate(Bundle savedInstanceState) {
        // Always call the super method first
        super.onCreate(savedInstanceState);
        ...
        // Initializes the loader
        getLoaderManager().initLoader(0, null, this);

实现 onCreateLoader()

实现方法 onCreateLoader()，该方法在您调用 initLoader() 后立即由加载器框架调用。

在 onCreateLoader() 中，设置搜索字符串模式。要将字符串转换为模式，请插入“%”（百分号）字符来表示零个或多个字符的序列，或“_”（下划线）字符来表示单个字符，或两者兼有。例如，模式“%Jefferson%”将同时匹配“Thomas Jefferson”和“Jefferson Davis”。

从方法中返回一个新的 CursorLoader。对于内容 URI，请使用 Contacts.CONTENT_URI。此 URI 指的是整个表，如以下示例所示

    ...
    override fun onCreateLoader(loaderId: Int, args: Bundle?): Loader<Cursor> {
        /*
         * Makes search string into pattern and
         * stores it in the selection array
         */
        selectionArgs[0] = "%$mSearchString%"
        // Starts the query
        return activity?.let {
            return CursorLoader(
                    it,
                    ContactsContract.Contacts.CONTENT_URI,
                    PROJECTION,
                    SELECTION,
                    selectionArgs,
                    null
            )
        } ?: throw IllegalStateException()
    }

    ...
    @Override
    public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) {
        /*
         * Makes search string into pattern and
         * stores it in the selection array
         */
        selectionArgs[0] = "%" + searchString + "%";
        // Starts the query
        return new CursorLoader(
                getActivity(),
                ContactsContract.Contacts.CONTENT_URI,
                PROJECTION,
                SELECTION,
                selectionArgs,
                null
        );
    }

实现 onLoadFinished() 和 onLoaderReset()

实现 onLoadFinished() 方法。当联系人提供者返回查询结果时，加载器框架会调用 onLoadFinished()。在此方法中，将结果 Cursor 放入 SimpleCursorAdapter 中。这会自动使用搜索结果更新 ListView

    override fun onLoadFinished(loader: Loader<Cursor>, cursor: Cursor) {
        // Put the result Cursor in the adapter for the ListView
        cursorAdapter?.swapCursor(cursor)
    }

    @Override
    public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) {
        // Put the result Cursor in the adapter for the ListView
        cursorAdapter.swapCursor(cursor);
    }

当加载器框架检测到结果 Cursor 包含陈旧数据时，会调用方法 onLoaderReset()。删除 SimpleCursorAdapter 对现有 Cursor 的引用。如果您不这样做，加载器框架将不会回收 Cursor，这会导致内存泄漏。例如

    override fun onLoaderReset(loader: Loader<Cursor>) {
        // Delete the reference to the existing Cursor
        cursorAdapter?.swapCursor(null)
    }

    @Override
    public void onLoaderReset(Loader<Cursor> loader) {
        // Delete the reference to the existing Cursor
        cursorAdapter.swapCursor(null);

    }

您现在拥有将搜索字符串与联系人姓名匹配并以 ListView 显示结果的应用程序的关键部分。用户可以点击联系人姓名来选择它。这将触发监听器，您可以在其中对联系人的数据进行进一步操作。例如，您可以检索联系人的详细信息。要了解如何执行此操作，请继续学习下一课，检索联系人的详细信息。

要了解有关搜索用户界面的更多信息，请阅读 API 指南 创建搜索界面。

本课程中剩余的部分演示了在联系人提供者中查找联系人的其他方法。

按特定数据类型匹配联系人

这种技术允许您指定要匹配的数据类型。按姓名检索是此类查询的特定示例，但您也可以对与联系人关联的任何类型详细信息数据执行此操作。例如，您可以检索具有特定邮政编码的联系人；在这种情况下，搜索字符串必须与存储在邮政编码行中的数据匹配。

要实现此类型的检索，首先实现以下代码，如上一节中列出

• 请求读取提供者的权限。
• 定义 ListView 和项目布局。
• 定义显示联系人列表的 Fragment。
• 定义全局变量。
• 初始化 Fragment。
• 为 ListView 设置 CursorAdapter。
• 设置所选联系人的监听器。
• 为 Cursor 列索引定义常量。

  虽然您是从不同的表中检索数据，但投影中列的顺序是相同的，因此您可以为 Cursor 使用相同的索引。

• 定义 onItemClick() 方法。
• 初始化加载器。
• 实现 onLoadFinished() 和 onLoaderReset()。

以下步骤将向您展示将搜索字符串与特定类型的详细信息数据匹配并显示结果所需的额外代码。

选择数据类型和表

要搜索特定类型的详细信息，您需要知道数据类型的自定义 MIME 类型值。每个数据类型都有一个唯一的 MIME 类型值，由 CONTENT_ITEM_TYPE 常量定义，该常量位于与数据类型相关的 ContactsContract.CommonDataKinds 子类中。子类名称表明其数据类型；例如，电子邮件数据的子类是 ContactsContract.CommonDataKinds.Email，电子邮件数据的自定义 MIME 类型由常量 Email.CONTENT_ITEM_TYPE 定义。

使用 ContactsContract.Data 表进行搜索。您在投影、选择子句和排序顺序中所需的所有常量都在此表中定义或继承自此表。

定义投影

要定义投影，请选择 ContactsContract.Data 或其继承的类中定义的一个或多个列。Contacts Provider 在返回行之前会在 ContactsContract.Data 和其他表之间进行隐式连接。例如

@SuppressLint("InlinedApi")
private val PROJECTION: Array<out String> = arrayOf(
        /*
         * The detail data row ID. To make a ListView work,
         * this column is required.
         */
        ContactsContract.Data._ID,
        // The primary display name
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB)
            ContactsContract.Data.DISPLAY_NAME_PRIMARY
        else
            ContactsContract.Data.DISPLAY_NAME,
        // The contact's _ID, to construct a content URI
        ContactsContract.Data.CONTACT_ID,
        // The contact's LOOKUP_KEY, to construct a content URI
        ContactsContract.Data.LOOKUP_KEY
)

    @SuppressLint("InlinedApi")
    private static final String[] PROJECTION =
        {
            /*
             * The detail data row ID. To make a ListView work,
             * this column is required.
             */
            ContactsContract.Data._ID,
            // The primary display name
            Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB ?
                    ContactsContract.Data.DISPLAY_NAME_PRIMARY :
                    ContactsContract.Data.DISPLAY_NAME,
            // The contact's _ID, to construct a content URI
            ContactsContract.Data.CONTACT_ID,
            // The contact's LOOKUP_KEY, to construct a content URI
            ContactsContract.Data.LOOKUP_KEY // A permanent link to the contact
        };

定义搜索条件

要搜索特定数据类型中的字符串，请从以下内容构建选择子句

• 包含搜索字符串的列的名称。此名称因数据类型而异，因此您需要找到与数据类型相对应的 ContactsContract.CommonDataKinds 子类，然后从该子类中选择列名。例如，要搜索电子邮件地址，请使用列 Email.ADDRESS。
• 搜索字符串本身，在选择子句中表示为“？”字符。
• 包含自定义 MIME 类型值的列的名称。此名称始终为 Data.MIMETYPE。
• 数据类型的自定义 MIME 类型值。如前所述，这是 ContactsContract.CommonDataKinds 子类中的 CONTENT_ITEM_TYPE 常量。例如，电子邮件数据的 MIME 类型值为 Email.CONTENT_ITEM_TYPE。通过在常量的开头和结尾连接一个“'”（单引号）字符，将该值用单引号括起来；否则，提供程序会将该值解释为变量名而不是字符串值。您不需要为此值使用占位符，因为您使用的是常量而不是用户提供的的值。

例如

/*
 * Constructs search criteria from the search string
 * and email MIME type
 */
private val SELECTION: String =
        /*
         * Searches for an email address
         * that matches the search string
         */
        "${Email.ADDRESS} LIKE ? AND " +
        /*
         * Searches for a MIME type that matches
         * the value of the constant
         * Email.CONTENT_ITEM_TYPE. Note the
         * single quotes surrounding Email.CONTENT_ITEM_TYPE.
         */
        "${ContactsContract.Data.MIMETYPE } = '${Email.CONTENT_ITEM_TYPE}'"

    /*
     * Constructs search criteria from the search string
     * and email MIME type
     */
    private static final String SELECTION =
            /*
             * Searches for an email address
             * that matches the search string
             */
            Email.ADDRESS + " LIKE ? " + "AND " +
            /*
             * Searches for a MIME type that matches
             * the value of the constant
             * Email.CONTENT_ITEM_TYPE. Note the
             * single quotes surrounding Email.CONTENT_ITEM_TYPE.
             */
            ContactsContract.Data.MIMETYPE + " = '" + Email.CONTENT_ITEM_TYPE + "'";

接下来，定义变量以包含选择参数

    private var searchString: String? = null
    private val selectionArgs: Array<String> = arrayOf("")

    String searchString;
    String[] selectionArgs = { "" };

实现 onCreateLoader()

现在您已指定了想要的数据以及查找数据的方法，请在 onCreateLoader() 的实现中定义一个查询。从此方法中返回一个新的 CursorLoader，使用投影、选择文本表达式和选择数组作为参数。对于内容 URI，请使用 Data.CONTENT_URI。例如

    override fun onCreateLoader(id: Int, args: Bundle?): Loader<Cursor> {
        // OPTIONAL: Makes search string into pattern
        searchString = "%$mSearchString%"

        searchString?.also {
            // Puts the search string into the selection criteria
            selectionArgs[0] = it
        }
        // Starts the query
        return activity?.let {
            CursorLoader(
                    it,
                    ContactsContract.Data.CONTENT_URI,
                    PROJECTION,
                    SELECTION,
                    selectionArgs,
                    null
            )
        } ?: throw IllegalStateException()
    }

@Override
    public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) {
        // OPTIONAL: Makes search string into pattern
        searchString = "%" + searchString + "%";
        // Puts the search string into the selection criteria
        selectionArgs[0] = searchString;
        // Starts the query
        return new CursorLoader(
                getActivity(),
                Data.CONTENT_URI,
                PROJECTION,
                SELECTION,
                selectionArgs,
                null
        );
    }

这些代码片段是基于特定类型的详细信息进行简单反向查找的基础。如果您的应用侧重于特定类型的数据，例如电子邮件，并且您希望允许用户获取与数据片段相关的名称，则这是最佳技术。

通过任何类型的数据匹配联系人

基于任何类型的数据检索联系人，如果联系人的任何数据与搜索字符串匹配，包括姓名、电子邮件地址、邮政地址、电话号码等，则会返回联系人。这将导致一组广泛的搜索结果。例如，如果搜索字符串是“Doe”，则搜索任何数据类型都会返回联系人“John Doe”；它还会返回住在“Doe Street”的联系人。

要实现此类型的检索，首先实现以下代码，如上一节中列出

• 请求读取提供者的权限。
• 定义 ListView 和项目布局。
• 定义显示联系人列表的 Fragment。
• 定义全局变量。
• 初始化 Fragment。
• 为 ListView 设置 CursorAdapter。
• 设置所选联系人的监听器。
• 定义投影。
• 为 Cursor 列索引定义常量。

  对于此类型的检索，您使用的是与“按姓名匹配联系人并列出结果”部分中相同的表。也使用相同的列索引。

• 定义 onItemClick() 方法。
• 初始化加载器。
• 实现 onLoadFinished() 和 onLoaderReset()。

以下步骤将向您展示将搜索字符串与任何类型的数据匹配并显示结果所需的额外代码。

删除选择条件

不要定义 SELECTION 常量或 mSelectionArgs 变量。这些在使用此类型的检索时不会使用。

实现 onCreateLoader()

实现 onCreateLoader() 方法，返回一个新的 CursorLoader。您不需要将搜索字符串转换为模式，因为 Contacts Provider 会自动执行此操作。使用 Contacts.CONTENT_FILTER_URI 作为基本 URI，并通过调用 Uri.withAppendedPath() 将您的搜索字符串附加到它。使用此 URI 会自动触发对任何数据类型的搜索，如下面的示例所示

    override fun onCreateLoader(loaderId: Int, args: Bundle?): Loader<Cursor> {
        /*
         * Appends the search string to the base URI. Always
         * encode search strings to ensure they're in proper
         * format.
         */
        val contentUri: Uri = Uri.withAppendedPath(
                ContactsContract.Contacts.CONTENT_FILTER_URI,
                Uri.encode(searchString)
        )
        // Starts the query
        return activity?.let {
            CursorLoader(
                    it,
                    contentUri,
                    PROJECTION2,
                    null,
                    null,
                    null
            )
        } ?: throw IllegalStateException()
    }

    @Override
    public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) {
        /*
         * Appends the search string to the base URI. Always
         * encode search strings to ensure they're in proper
         * format.
         */
        Uri contentUri = Uri.withAppendedPath(
                Contacts.CONTENT_FILTER_URI,
                Uri.encode(searchString));
        // Starts the query
        return new CursorLoader(
                getActivity(),
                contentUri,
                PROJECTION,
                null,
                null,
                null
        );
    }

这些代码片段是进行 Contacts Provider 广泛搜索的应用程序的基础。此技术适用于想要实现类似于 People 应用的联系人列表屏幕功能的应用程序。