بازیابی فهرست مخاطبین

این درس به شما نشان می‌دهد که چگونه بااستفاده از تکنیک‌های زیر، فهرستی از مخاطبین را که داده‌هایشان با تمام یا بخشی از یک رشته جستجو مطابقت دارد بازیابی کنید:

مطابقت دادن نام مخاطبین
فهرستی از مخاطبین را با مطابقت دادن رشته جستجو با همه یا بخشی از داده‌های نام مخاطب بازیابی کنید. «ارائه‌کننده مخاطبین» اجازه می‌دهد چند نمونه از یک نام وجود داشته باشد، بنابراین این تکنیک می‌تواند فهرستی از موارد منطبق را برگرداند.
با نوع خاصی از داده‌ها، مثل شماره تلفن، مطابقت داشته باشد
بازیابی فهرست مخاطبین با مطابقت دادن رشته جستجو با نوع خاصی از داده‌های جزئیات مثل نشانی ایمیل. برای مثال، این تکنیک به شما امکان می‌دهد همه مخاطبینی را که نشانی ایمیلشان با رشته جستجو مطابقت دارد فهرست کنید.
مطابقت با هر نوع داده
فهرستی از مخاطبین را با مطابقت دادن رشته جستجو با هر نوع داده جزئیات، ازجمله نام، شماره تلفن، نشانی خیابان، نشانی ایمیل، و غیره بازیابی کنید. برای مثال، این تکنیک به شما امکان می‌دهد هر نوع داده‌ای را برای رشته جستجو بپذیرید و سپس مخاطبینی را که داده‌هایشان با رشته مطابقت دارد فهرست کنید.

توجه: همه مثال‌های این درس از CursorLoader برای بازیابی داده‌ها از «ارائه‌کننده مخاطبین» استفاده می‌کنند. ‫CursorLoader پُرسمان خود را در رشته‌ای اجرا می‌کند که از رشته میانای کاربر جدا است. این کار تضمین می‌کند که پُرسمان زمان پاسخ میانای کاربر را کند نمی‌کند و باعث تجربه کاربری ضعیف نمی‌شود. برای اطلاعات بیشتر، کلاس آموزشی Android بار کردن داده‌ها در پس‌زمینه را ببینید.

درخواست اجازه برای خواندن ارائه‌دهنده

برای انجام هر نوع جستجویی در «ارائه‌دهنده مخاطبین»، برنامه‌تان باید اجازه READ_CONTACTS را داشته باشد. برای درخواست این مورد، این عنصر <uses-permission> را به‌عنوان عنصر فرزند <manifest> به فایل مانیفست خود اضافه کنید:

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

مطابقت دادن مخاطب براساس نام و فهرست کردن نتایج

این تکنیک سعی می‌کند رشته جستجو را با نام مخاطب یا مخاطبین در جدول ContactsContract.Contacts «ارائه‌دهنده مخاطب» مطابقت دهد. معمولاً می‌خواهید نتایج را در ListView نمایش دهید تا کاربر بتواند از بین مخاطبین منطبق انتخاب کند.

تعریف ListView و طرح‌بندی‌های مورد

برای نمایش نتایج جستجو در ListView، به فایل چیدمان اصلی نیاز دارید که کل میانای کاربر ازجمله 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 استفاده می‌کند.

فایل چیدمان مورد contacts_list_item.xml را با 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 استفاده می‌کند.

توجه: این درس میانای کاربر را برای دریافت رشته جستجو از کاربر شرح نمی‌دهد، زیرا ممکن است بخواهید رشته را به‌طور غیرمستقیم دریافت کنید. برای مثال، می‌توانید به کاربر گزینه‌ای برای جستجوی مخاطبینی که نامشان با رشته‌ای در پیامک ورودی مطابقت دارد ارائه دهید.

دو فایل چیدمانی که نوشته‌اید واسط کاربری را تعریف می‌کنند که ListView را نشان می‌دهد. مرحله بعدی نوشتن کدی است که از این میانای کاربر برای نمایش فهرست مخاطبین استفاده می‌کند.

تعریف Fragment که فهرست مخاطبین را نمایش می‌دهد

برای نمایش فهرست مخاطبین، ابتدا یک Fragment تعریف کنید که توسط یک Activity بارگیری می‌شود. استفاده از Fragment روش انعطاف‌پذیرتری است، زیرا می‌توانید از یک Fragment برای نمایش فهرست و از Fragment دوم برای نمایش جزئیات مخاطبی که کاربر از فهرست انتخاب می‌کند استفاده کنید. بااستفاده از این رویکرد، می‌توانید یکی از تکنیک‌های ارائه‌شده در این درس را با یکی از تکنیک‌های درس بازیابی جزئیات مخاطب ترکیب کنید.

برای آشنایی با نحوه استفاده از یک یا چند شیء Fragment از Activity، کلاس آموزشی ساخت میانای کاربر پویا با Fragment را بخوانید.

برای کمک به شما در نوشتن پُرسمان‌ها در «ارائه‌کننده مخاطبین»، چارچوب Android یک کلاس قرارداد به‌نام ContactsContract ارائه می‌دهد که ثابت‌ها و روش‌های مفیدی را برای دسترسی به ارائه‌کننده تعریف می‌کند. وقتی از این کلاس استفاده می‌کنید، لازم نیست ثابت‌های خودتان را برای شناسه منبع یکسان محتوا، نام جدول، یا ستون‌ها تعریف کنید. برای استفاده از این کلاس، عبارت زیر را اضافه کنید:

کاتلین

import android.provider.ContactsContract

جاوا

import android.provider.ContactsContract;

ازآنجایی‌که کد از CursorLoader برای بازیابی داده‌ها از ارائه‌دهنده استفاده می‌کند، باید مشخص کنید که واسط بارکننده LoaderManager.LoaderCallbacks را پیاده‌سازی می‌کند. همچنین، برای کمک به تشخیص اینکه کاربر کدام مخاطب را از فهرست نتایج جستجو انتخاب می‌کند، میانای آداپتور AdapterView.OnItemClickListener را پیاده‌سازی کنید. برای مثال:

کاتلین

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

جاوا

...
import android.widget.AdapterView;
import androidx.fragment.app.Fragment;
import androidx.loader.app.LoaderManager;
...
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 نسخه ۳.۰ (میانای برنامه‌سازی کاربردی نسخه ۱۱) یا بالاتر نیاز دارد، تنظیم minSdkVersion برنامه روی ۱۰ یا کمتر باعث ایجاد هشدار Android Lint در Android Studio می‌شود. برای خاموش کردن این هشدار، حاشیه‌نویسی @SuppressLint("InlinedApi") را قبل‌از تعریف FROM_COLUMNS اضافه کنید.

مقداردهی اولیه Fragment

Fragment را مقداردهی اولیه کنید. سازنده عمومی خالی موردنیاز سیستم Android را اضافه کنید و میانای کاربر شیء Fragment را در روش بازخوان onCreateView() گسترش دهید. برای مثال:

کاتلین

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

راه‌اندازی CursorAdapter برای ListView

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

تنظیم شنونده مخاطب انتخاب‌شده

وقتی نتایج جستجو را نمایش می‌دهید، معمولاً می‌خواهید به کاربر اجازه دهید یک مخاطب را برای پردازش بیشتر انتخاب کند. برای مثال، وقتی کاربر روی مخاطبی کلیک می‌کند، می‌توانید نشانی مخاطب را روی نقشه نمایش دهید. برای ارائه این ویژگی، ابتدا Fragment فعلی را به‌عنوان شنونده کلیک تعریف کردید و مشخص کردید که کلاس AdapterView.OnItemClickListener را پیاده‌سازی می‌کند، همان‌طور که در بخش تعریف قطعه‌ای که فهرست مخاطبین را نمایش می‌دهد نشان داده شده است.

برای ادامه راه‌اندازی شنونده، آن را با فراخوانی روش setOnItemClickListener() در onActivityCreated() به 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 فعلی OnItemClickListener برای ListView است، اکنون باید روش الزامی آن onItemClick() را پیاده‌سازی کنید که رویداد کلیک را مدیریت می‌کند. این موضوع در بخش بعدی شرح داده شده است.

تعریف کردن تصویرسازی

ثابتی را تعریف کنید که حاوی ستون‌هایی باشد که می‌خواهید از پُرسمانتان برگردانید. هر مورد در ListView نام نمایشی مخاطب را نشان می‌دهد، که حاوی شکل اصلی نام مخاطب است. در Android 3.0 (نسخه میانای برنامه‌سازی کاربردی ۱۱) و نسخه‌های جدیدتر، نام این ستون Contacts.DISPLAY_NAME_PRIMARY است؛ در نسخه‌های قدیمی‌تر، نام آن Contacts.DISPLAY_NAME است.

ستون Contacts._ID توسط فرایند اتصال SimpleCursorAdapter استفاده می‌شود. Contacts._ID و LOOKUP_KEY باهم استفاده می‌شوند تا شناسه منبع یکسان محتوایی برای مخاطبی که کاربر انتخاب می‌کند ساخته شود.

کاتلین

...
@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 تعریف کنید، زیرا نمایه‌ها با ترتیب نام ستون‌ها در طرح‌ریزی شما یکسان هستند. برای مثال:

کاتلین

// 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.getInstance(this).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
        LoaderManager.getInstance(this).initLoader(0, null, this);

پیاده‌سازی onCreateLoader()‎

روش onCreateLoader() را پیاده‌سازی کنید که بلافاصله پس‌از فراخوانی initLoader() توسط چارچوب بارکننده فراخوانی می‌شود.

در onCreateLoader()، الگوی رشته جستجو را تنظیم کنید. برای تبدیل رشته به الگو، نویسه‌های «%» (درصد) را برای نشان دادن توالی صفر یا چند نویسه، یا نویسه‌های «_» (زیرخط) را برای نشان دادن یک نویسه، یا هر دو را وارد کنید. برای مثال، الگوی «%Jefferson%» با هر دو «Thomas Jefferson» و «Jefferson Davis» مطابقت دارد.

CursorLoader جدیدی را از روش برگردانید. برای شناسه منبع یکسان محتوا، از 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.
  • CursorAdapter را برای ListView راه‌اندازی کنید.
  • تنظیم شنونده مخاطب انتخاب‌شده.
  • ثابت‌ها را برای نمایه‌های ستون «مکان‌نما» تعریف کنید.

    اگرچه داده‌ها را از جدول دیگری بازیابی می‌کنید، ترتیب ستون‌ها در طرح یکسان است، بنابراین می‌توانید از همان نمایه‌ها برای Cursor استفاده کنید.

  • روش onItemClick()‎ را تعریف کنید.
  • مقداردهی اولیه بارکننده.
  • ‫()onLoadFinished و ()onLoaderReset را پیاده‌سازی کنید.

مراحل زیر کد اضافی موردنیاز برای مطابقت دادن رشته جستجو با نوع خاصی از داده‌های جزئیات و نمایش نتایج را نشان می‌دهد.

نوع داده و جدول را انتخاب کنید

برای جستجوی نوع خاصی از داده‌های جزئیات، باید مقدار نوع MIME سفارشی را برای نوع داده بدانید. هر نوع داده دارای مقدار نوع MIME یکتایی است که با ثابت CONTENT_ITEM_TYPE در زیرکلاس ContactsContract.CommonDataKinds مرتبط با نوع داده تعریف می‌شود. زیرکلاس‌ها نام‌هایی دارند که نوع داده آن‌ها را نشان می‌دهد؛ برای مثال، زیرکلاس برای داده‌های ایمیل ContactsContract.CommonDataKinds.Email است، و نوع MIME سفارشی برای داده‌های ایمیل با ثابت Email.CONTENT_ITEM_TYPE تعریف می‌شود.

از جدول ContactsContract.Data برای جستجو استفاده کنید. همه ثابت‌هایی که برای طرح‌ریزی، عبارت انتخاب، و ترتیب مرتب‌سازی نیاز دارید در این جدول تعریف شده‌اند یا از آن به ارث برده شده‌اند.

تعریف کردن تصویرسازی

برای تعریف کردن فرافکنی، یک یا چند ستون تعریف‌شده در ContactsContract.Data یا کلاس‌هایی را که از آن ارث می‌برد انتخاب کنید. «ارائه‌کننده مخاطبین» قبل‌از برگرداندن ردیف‌ها، پیوستن ضمنی بین 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 سفارشی برای نوع داده. همان‌طور که قبلاً توضیح داده شد، این ثابت CONTENT_ITEM_TYPE در زیرکلاس ContactsContract.CommonDataKinds است. برای مثال، مقدار نوع 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 جدیدی را از این روش برگردانید و از طرح‌ریزی، عبارت نوشتاری انتخاب، و آرایه انتخاب به‌عنوان آرگومان استفاده کنید. برای شناسه منبع یکسان محتوا، از 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.
  • CursorAdapter را برای ListView راه‌اندازی کنید.
  • تنظیم شنونده مخاطب انتخاب‌شده.
  • طرحی را تعریف کنید.
  • ثابت‌ها را برای نمایه‌های ستون «مکان‌نما» تعریف کنید.

    برای این نوع بازیابی، از همان جدولی استفاده می‌کنید که در بخش مطابقت دادن مخاطب براساس نام و فهرست کردن نتایج استفاده کردید. از همان نمایه‌های ستون نیز استفاده کنید.

  • روش onItemClick()‎ را تعریف کنید.
  • مقداردهی اولیه بارکننده.
  • ‫()onLoadFinished و ()onLoaderReset را پیاده‌سازی کنید.

مراحل زیر کد اضافی موردنیاز برای مطابقت دادن رشته جستجو با هر نوع داده و نمایش نتایج را نشان می‌دهد.

برداشتن معیارهای انتخاب

ثابت‌های SELECTION یا متغیر mSelectionArgs را تعریف نکنید. از این‌ها در این نوع بازیابی استفاده نمی‌شود.

پیاده‌سازی onCreateLoader()‎

روش onCreateLoader() را پیاده‌سازی کنید و CursorLoader جدیدی را برگردانید. نیازی نیست رشته جستجو را به الگو تبدیل کنید، زیرا «ارائه‌دهنده مخاطبین» این کار را به‌طور خودکار انجام می‌دهد. از Contacts.CONTENT_FILTER_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
        );
    }

این تکه‌کدها پایه برنامه‌ای هستند که جستجوی گسترده‌ای در «ارائه‌کننده مخاطبین» انجام می‌دهد. این تکنیک برای برنامه‌هایی مفید است که می‌خواهند عملکردی مشابه صفحه فهرست مخاطبین برنامه «افراد» را پیاده‌سازی کنند.