Note：這一課的所有例子都使用CursorLoader獲取Contacts Provider中的數(shù)據(jù)。CursorLoader在一個與UI線程相獨立的工作線程進行查詢操作。這保證了數(shù)據(jù)查詢不會降低UI響應(yīng)的時間，以免引起槽糕的用戶體驗。更多信息，請參照在后臺加載數(shù)據(jù)。

請求讀取聯(lián)系人的權(quán)限

為了能夠在Contacts Provider中做任意類型的搜索，我們的應(yīng)用必須擁有READ_CONTACTS權(quán)限。為了擁有這個權(quán)限，我們需要在項目的manifest文件的<manifest>節(jié)點中添加子結(jié)點，如下：

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

根據(jù)名字取得聯(lián)系人并列出結(jié)果

這種方法根據(jù)搜索字符串，去匹配Contacts Provider的ContactsContract.Contacts表中的聯(lián)系人名字。通常希望在ListView中展示結(jié)果，去讓用戶在所有匹配的聯(lián)系人中做選擇。

定義ListView和列表項的布局

為了能夠?qū)⑺阉鹘Y(jié)果展示在列表中，我們需要一個包含ListView以及其他布局控件的主布局文件，和一個定義列表中每一項的布局文件。例如，可以使用以下XML代碼去創(chuàng)建主布局文件res/layout/contacts_list_view.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內(nèi)建的ListView控件,他的id是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內(nèi)建的TextView控件,他的id是android:text1。

Note：本課并不會描述如何從用戶那里獲取搜索字符串的界面，因為我們可能會間接地獲取這個字符串。比如說，我們可能會給用戶一個選項去輸入文字信息，把這些文字信息作為搜索字符串去匹配聯(lián)系人的名字。

剛剛寫的這兩個布局文件定義了一個顯示ListView的用戶界面。下一步是編寫使用這個用戶界面顯示聯(lián)系人列表的代碼。

定義一個顯示聯(lián)系人列表的Fragment

為了顯示聯(lián)系人列表，需要定義一個由Activity加載的Fragment。使用Fragment是一個比較靈活的方法，因為我們可以使用一個Fragment去顯示列表，用另一個Fragment顯示用戶在列表中選擇的聯(lián)系人的詳情。使用這種方式，我們可以將本課程中展示的方法和另外一課獲取聯(lián)系人詳情的方法聯(lián)系起來。

想要學(xué)習(xí)如何在Activity中使用一個或者多個Fragment，請閱讀培訓(xùn)課程使用Fragment建立動態(tài)UI。

為了方便我們編寫對Contacts Provider的查詢，Android框架提供了一個叫做ContactsContract的契約類，這個類定義了一些對查詢Contacts Provider很有用的常量和方法。當(dāng)我們使用這個類的時候，我們不用自己定義內(nèi)容URI、表名、列名等常量。使用這個類，只需要引入以下類聲明：

import android.provider.ContactsContract;

由于代碼中使用了CursorLoader去獲取provider的數(shù)據(jù)，所以我們必須實現(xiàn)加載器接口LoaderManager.LoaderCallbacks。同時，為了檢測用戶從結(jié)果列表中選擇了哪一個聯(lián)系人，必須實現(xiàn)適配器接口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 final static String[] FROM_COLUMNS = {
        Build.VERSION.SDK_INT
                >= Build.VERSION_CODES.HONEYCOMB ?
                Contacts.DISPLAY_NAME_PRIMARY :
                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 mContactsList;
// Define variables for the contact the user selects
// The contact's _ID value
long mContactId;
// The contact's LOOKUP_KEY
String mContactKey;
// A content URI for the selected contact
Uri mContactUri;
// An adapter that binds the result Cursor to the ListView
private SimpleCursorAdapter mCursorAdapter;
...

Note：由于Contacts.DISPLAY_NAME_PRIMARY需要在Android 3.0（API版本11）或者更高的版本才能使用，如果應(yīng)用的minSdkVersion是10或者更低，會在eclipse中產(chǎn)生警告信息。為了關(guān)閉這個警告，我們可以在FROM_COLUMNS定義之前加上@SuppressLint("InlinedApi")注解。

初始化Fragment

為了初始化Fragment，Android系統(tǒng)需要我們?yōu)檫@個Fragment添加空的、公有的構(gòu)造方法，同時在回調(diào)方法onCreateView()中綁定界面。例如：

// 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設(shè)置CursorAdapter

設(shè)置SimpleCursorAdapter，將搜索結(jié)果綁定到ListView。為了獲得顯示聯(lián)系人列表的ListView控件，需要使用Fragment的父Activity調(diào)用Activity.findViewById()。當(dāng)調(diào)用setAdapter()的時候，需要使用父Activity的上下文（Context）。

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

為選擇的聯(lián)系人設(shè)置監(jiān)聽器

當(dāng)我們顯示搜索列表結(jié)果的時候，我們通常會讓用戶選擇某一個聯(lián)系人去做進一步的處理。例如，當(dāng)用戶選擇某一個聯(lián)系人的時候，可以在地圖上顯示這個聯(lián)系人的地址。為了能夠提供這個功能，我們需要定義當(dāng)前的Fragment為一個點擊監(jiān)聽器，這需要這個類實現(xiàn)AdapterView.OnItemClickListener接口，就像前面介紹的定義顯示聯(lián)系人列表的Fragment那樣。

繼續(xù)設(shè)置這個監(jiān)聽器，需要在onActivityCreated()方法中調(diào)用setOnItemClickListener()以使得這個監(jiān)聽器綁定到ListView。例如：

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

由于指定了當(dāng)前的Fragment作為ListView的點擊監(jiān)聽器，現(xiàn)在我們需要實現(xiàn)處理點擊事件的onItemClick()方法。這個會在隨后討論。

定義查詢映射

定義一個常量，這個常量包含我們想要從查詢結(jié)果中返回的列。Listview中的每一項顯示了一個聯(lián)系人的名字。在Android 3.0（API version 11）或者更高的版本，這個列的名字是Contacts.DISPLAY_NAME_PRIMARY；在Android 3.0之前，這個列的名字是Contacts.DISPLAY_NAME。

在SimpleCursorAdapter綁定過程中會用到Contacts._ID列。 Contacts._ID和LOOKUP_KEY一同用來構(gòu)建用戶選擇的聯(lián)系人的內(nèi)容URI。

...
@SuppressLint("InlinedApi")
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
};

定義Cursor的列索引常量

為了從Cursor中獲得單獨某一列的數(shù)據(jù)，我們需要知道這一列在Cursor中的索引值。我們需要定義Cursor列的索引值，這些索引值與我們定義查詢映射的列的順序是一樣的。例如：

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

指定查詢標(biāo)準(zhǔn)

為了指定我們想要的數(shù)據(jù)，我們需要創(chuàng)建一個包含文本表達(dá)式和變量的組合，去告訴provider我們需要的數(shù)據(jù)列和想要的值。

對于文本表達(dá)式，定義一個常量，列出所有搜索到的列。盡管這個表達(dá)式可以包含變量值，但是建議用"?"占位符來替代這個值。在搜索的時候，占位符里的值會被數(shù)組里的值所取代。使用"?"占位符確保了搜索條件是由綁定產(chǎn)生而不是由SQL編譯產(chǎn)生。這個方法消除了惡意SQL注入的可能。例如：

// 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 mSearchString;
// Defines the array to hold values that replace the ?
private String[] mSelectionArgs = { mSearchString };

定義onItemClick()方法

在之前的內(nèi)容中，我們?yōu)長istview設(shè)置了列表項點擊監(jiān)聽器，現(xiàn)在需要定義AdapterView.OnItemClickListener.onItemClick()方法以實現(xiàn)監(jiān)聽器行為：

@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
    mContactId = getLong(CONTACT_ID_INDEX);
    // Get the selected LOOKUP KEY
    mContactKey = getString(CONTACT_KEY_INDEX);
    // Create the contact's content Uri
    mContactUri = Contacts.getLookupUri(mContactId, mContactKey);
    /*
     * You can use mContactUri as the content URI for retrieving
     * the details for a contact.
     */
}

初始化Loader

由于使用了CursorLoader獲取數(shù)據(jù)，我們必須初始化后臺線程和其他的控制異步獲取數(shù)據(jù)的變量。需要在onActivityCreated()方法中做初始化的工作，這個方法是在Fragment的界面顯示之前被調(diào)用的，相關(guān)代碼展示如下：

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

實現(xiàn)onCreateLoader()方法

我們需要實現(xiàn)onCreateLoader()方法，這個方法是在調(diào)用initLoader()后馬上被loader框架調(diào)用的。

在onCreateLoader()方法中，設(shè)置搜索字符串模式。為了讓一個字符串符合一個模式，插入"%"字符代表0個或多個字符，插入"_"代表一個字符。例如，模式%Jefferson%將會匹配“Thomas Jefferson”和“Jefferson Davis”。

這個方法返回一個CursorLoader對象。對于內(nèi)容URI，則使用了Contacts.CONTENT_URI，這個URI關(guān)聯(lián)到整個表，例子如下所示：

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

實現(xiàn)onLoadFinished()方法和onLoaderReset()方法

實現(xiàn)onLoadFinished()方法。當(dāng)Contacts Provider返回查詢結(jié)果的時候，loader框架會調(diào)用onLoadFinished()方法。在這個方法中，將查詢結(jié)果Cursor傳給SimpleCursorAdapter，這將會使用這個搜索結(jié)果自動更新ListView。

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

當(dāng)loader框架檢測到結(jié)果集Cursor包含過時的數(shù)據(jù)時，它會調(diào)用onLoaderReset()。我們需要刪除SimpleCursorAdapter對已經(jīng)存在Cursor的引用。如果不這么做的話，loader框架將不會回收Cursor對象，這將會導(dǎo)致內(nèi)存泄漏。例如：

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

我們現(xiàn)在已經(jīng)實現(xiàn)了一個應(yīng)用的關(guān)鍵部分，即根據(jù)搜索字符串匹配聯(lián)系人名字和將獲得的結(jié)果展示在ListView中。用戶可以點擊選擇一個聯(lián)系人名字，這將會觸發(fā)一個監(jiān)聽器，在監(jiān)聽器的回調(diào)函數(shù)中，你可以使用此聯(lián)系人的數(shù)據(jù)做進一步的處理。例如，你可以進一步獲取此聯(lián)系人的詳情，想要知道何如獲取聯(lián)系人詳情，請繼續(xù)學(xué)習(xí)下一課獲取聯(lián)系人詳情。

想要了解更多搜索用戶界面的知識，請參考API指南Creating a Search Interface。

這一課的以下內(nèi)容展示了在Contacts Provider中查找聯(lián)系人的其他方法。

根據(jù)特定的數(shù)據(jù)類型匹配聯(lián)系人

這種方法可以讓我們指定想要匹配的數(shù)據(jù)類型。根據(jù)名字去檢索是這種類型的查詢的一個具體例子。但也可以用任何與聯(lián)系人詳情數(shù)據(jù)相關(guān)的數(shù)據(jù)類型去做查詢。例如，我們可以檢索具有特定郵政編碼聯(lián)系人，在這種情況下，搜索字符串將會去匹配存儲在一個郵政編碼列中的數(shù)據(jù)。

為了實現(xiàn)這種類型的檢索，首先實現(xiàn)以下的代碼，正如之前的內(nèi)容所展示的：

請求讀取聯(lián)系人的權(quán)限
定義列表和列表項的布局
定義顯示聯(lián)系人列表的Fragment
定義全局變量
初始化Fragment
為ListView設(shè)置CursorAdapter
設(shè)置選擇聯(lián)系人的監(jiān)聽器
定義Cursor的列索引常量

盡管我們現(xiàn)在從不同的表中取數(shù)據(jù)，檢索列的映射順序是一樣的，所以我們可以為這個Cursor使用同樣的索引常量。
定義onItemClick()方法
初始化loader
實現(xiàn)onLoadFinished()方法和onLoaderReset()方法

為了將搜索字符串匹配特定的詳請數(shù)據(jù)類型并顯示結(jié)果，以下的步驟展示了我們需要額外添加的代碼。

選擇要查詢的數(shù)據(jù)類型和數(shù)據(jù)庫表

為了從特定類型的詳請數(shù)據(jù)中查詢，我們必須知道的數(shù)據(jù)類型的自定義MIME類型的值。每一個數(shù)據(jù)類型擁有唯一的MIME類型值，這個值在ContactsContract.CommonDataKinds的子類中被定義為常量CONTENT_ITEM_TYPE，并且與實際的數(shù)據(jù)類型相關(guān)。子類的名字會表明它們的實際數(shù)據(jù)類型。例如，email數(shù)據(jù)的子類是ContactsContract.CommonDataKinds.Email，并且email的自定義MIME類型是Email.CONTENT_ITEM_TYPE。

在搜索中需要使用ContactsContract.Data類。同時所有需要的常量，包括數(shù)據(jù)映射、選擇字句、排序規(guī)則都是由這個類定義或繼承自此類。

定義查詢映射

為了定義一個查詢映射，請選擇一個或者多個定義在ContactsContract.Data表或其子類的列。Contacts Provider在返回行結(jié)果集之前，隱式的連接了ContactsContract.Data表和其他表。例如：

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

定義查詢標(biāo)準(zhǔn)

為了根據(jù)特定的聯(lián)系人數(shù)據(jù)類型查詢字符串，請按照以下方法構(gòu)建查詢選擇子句：

包含搜索字符串的列名。這個名字根據(jù)數(shù)據(jù)類型所變化，所以我們需要找到與數(shù)據(jù)類型對應(yīng)的ContactsContract.CommonDataKinds的子類，并從這個子類中選擇列名。例如，想要搜索email地址，需要使用Email.ADDRESS列。
搜索字符串本身，請在查詢選擇子句里使用"?"表示。
列名包含自定義的MIME類型值。這個列名字總是Data.MIMETYPE。
自定義MIME類型值的數(shù)據(jù)類型。如之前描述，這需要使用ContactsContract.CommonDataKinds子類中的CONTENT_ITEM_TYPE常量。例如，email數(shù)據(jù)的MIME類型值是Email.CONTENT_ITEM_TYPE。需要在這個常量值的開頭和結(jié)尾加上"'"（單引號）。否則，provider會把這個值翻譯成一個變量而不是一個字符串。我們不需要為這個值提供占位符，因為我們在使用一個常量而不是用戶提供的值。例如：

/*
 * 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.
     */
    Data.MIMETYPE + " = '" + Email.CONTENT_ITEM_TYPE + "'";

下一步，定義包含選擇字符串的變量：

String mSearchString;
String[] mSelectionArgs = { "" };

實現(xiàn)onCreateLoader()方法

現(xiàn)在，我們已經(jīng)詳述了想要的數(shù)據(jù)和如何找到這些數(shù)據(jù)，如何在onCreateLoader()方法中定義一個查詢。使用你的數(shù)據(jù)映射、查詢選擇表達(dá)式和一個數(shù)組作為選擇表達(dá)式的參數(shù)，并從這個方法中返回一個新的CursorLoader對象。而內(nèi)容URI需要使用Data.CONTENT_URI，例如：

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

這段代碼片段是基于特定的聯(lián)系人詳情數(shù)據(jù)類型的簡單反向查找。如果我們的應(yīng)用關(guān)注于某一種特定的數(shù)據(jù)類型，比如說email地址，并且允許用戶獲得與此數(shù)據(jù)相關(guān)的聯(lián)系人名字，這種形式的查詢是最好的方法。

根據(jù)任意類型的數(shù)據(jù)匹配聯(lián)系人

根據(jù)任意數(shù)據(jù)類型獲取聯(lián)系人時，如果聯(lián)系人的數(shù)據(jù)（這些數(shù)據(jù)包括名字、email地址、郵件地址和電話號碼等等）能匹配要搜索的字符串，那么該聯(lián)系人信息將會被返回。這種搜索結(jié)果會比較廣泛。例如，如果搜索字符串是"Doe"，搜索任意類型的數(shù)據(jù)將會返回名字為"Jone Doe"的聯(lián)系人，也會返回一個住在"Doe Street"的聯(lián)系人。

為了完成這種類型的查詢，就像之前展示的那樣，首先需要實現(xiàn)以下代碼：

請求讀取聯(lián)系人的權(quán)限
定義列表和列表項的布局
定義顯示聯(lián)系人列表的Fragment
定義全局變量
初始化Fragment
為ListView設(shè)置CursorAdapter
設(shè)置選擇聯(lián)系人的監(jiān)聽器
定義Cursor的列索引常量

對于這種形式的查詢，你需要使用與在“使用特定類型的數(shù)據(jù)匹配聯(lián)系人”那一節(jié)中相同的表，也可以使用相同的列索引。
定義onItemClick()方法
初始化loader
實現(xiàn)onLoadFinished()方法和onLoaderReset()方法

以下的步驟展示了為了能夠根據(jù)任意的數(shù)據(jù)類型去匹配查詢字符串并顯示結(jié)果列表，我們需要添加的額外代碼。

去除查詢標(biāo)準(zhǔn)

不需要為mSelectionArgs定義查詢標(biāo)準(zhǔn)常量SELECTION。這些內(nèi)容在這種類型的檢索不會被用到。

實現(xiàn)onCreateLoader()方法

實現(xiàn)onCreateLoader()方法，返回一個新的CursorLoader對象。我們不需要把搜索字符串轉(zhuǎn)化成一個搜索模式，因為Contacts Provider會自動做這件事。使用Contacts.CONTENT_FILTER_URI作為基礎(chǔ)查詢URI，并使用Uri.withAppendedPath()方法將搜索字符串添加到基礎(chǔ)URI中。使用這個URI會自動觸發(fā)對任意數(shù)據(jù)類型的搜索，就像以下例子所示：

@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(mSearchString));
    // Starts the query
    return new CursorLoader(
            getActivity(),
            contentUri,
            PROJECTION,
            null,
            null,
            null
    );
}

這段代碼片段，是想要在Contacts Provider中建立廣泛搜索類型應(yīng)用的基礎(chǔ)部分。這種方法對那些想要實現(xiàn)與通訊錄應(yīng)用聯(lián)系人列表中相似搜索功能的應(yīng)用，會很有幫助。

上一篇：檢測常用的手勢下一篇：Android分享操作(Building Apps with Content Sharing)