אחזור רשימה של אנשי קשר

בשיעור הזה נסביר איך לאחזר רשימה של אנשי קשר שהנתונים שלהם תואמים לכל מחרוזת החיפוש או לחלק ממנה, באמצעות השיטות הבאות:

התאמת שמות של אנשי קשר
אחזור רשימה של אנשי קשר על ידי התאמת מחרוזת החיפוש לכל נתוני השם של איש הקשר או לחלק מהם. ניהול אנשי הקשר מאפשר כמה מופעים של אותו שם, כך שהשיטה הזו יכולה להחזיר רשימה של התאמות.
התאמה לסוג ספציפי של נתונים, כמו מספר טלפון
אחזור רשימה של אנשי קשר על ידי התאמה של מחרוזת החיפוש לסוג מסוים של נתונים, כמו כתובת אימייל. לדוגמה, השיטה הזו מאפשרת לכם להציג את כל אנשי הקשר שכתובת האימייל שלהם תואמת למחרוזת החיפוש.
התאמה לכל סוג של נתונים
אחזור רשימה של אנשי קשר על ידי התאמת מחרוזת החיפוש לכל סוג של נתונים מפורטים, כולל שם, מספר טלפון, כתובת, כתובת אימייל וכו'. לדוגמה, השיטה הזו מאפשרת לקבל כל סוג של נתונים למחרוזת חיפוש, ואז להציג את אנשי הקשר שהנתונים שלהם תואמים למחרוזת.

הערה: בכל הדוגמאות בשיעור הזה נעשה שימוש ב-CursorLoader כדי לאחזר נתונים מניהול אנשי הקשר. ‫CursorLoader מריץ את השאילתה שלו בשרשור נפרד משרשור ה-UI. כך אפשר לוודא שהשאילתה לא תאט את זמני התגובה של ממשק המשתמש ותגרום לחוויית משתמש גרועה. מידע נוסף זמין בשיעור ההדרכה של 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.

הערה: השיעור הזה לא מתאר את ממשק המשתמש לקבלת מחרוזת חיפוש מהמשתמש, כי יכול להיות שתרצו לקבל את המחרוזת באופן עקיף. לדוגמה, אתם יכולים לתת למשתמש אפשרות לחפש אנשי קשר שהשם שלהם תואם למחרוזת בהודעת SMS נכנסת.

שני קובצי הפריסה שכתבתם מגדירים ממשק משתמש שמוצג בו ListView. השלב הבא הוא לכתוב קוד שמשתמש בממשק המשתמש הזה כדי להציג רשימה של אנשי קשר.

הגדרת Fragment שמציג את רשימת אנשי הקשר

כדי להציג את רשימת אנשי הקשר, קודם צריך להגדיר Fragment שנטען על ידי Activity. שימוש ב-Fragment הוא שיטה גמישה יותר, כי אפשר להשתמש ב-Fragment אחד כדי להציג את הרשימה וב-Fragment שני כדי להציג את הפרטים של איש הקשר שהמשתמש בוחר מהרשימה. בגישה הזו, אתם יכולים לשלב את אחת מהשיטות שמוצגות בשיעור הזה עם אחת מהשיטות מהשיעור אחזור פרטים של איש קשר.

כדי ללמוד איך להשתמש באובייקט Fragment אחד או יותר מ-Activity, קראו את שיעור ההדרכה יצירת ממשק משתמש דינמי באמצעות Fragments.

כדי לעזור לכם לכתוב שאילתות לניהול אנשי הקשר, מסגרת Android מספקת מחלקה של ערכים קבועים (contract class) שנקראת ContactsContract, שמגדירה קבועים ושיטות שימושיים לגישה לספק. כשמשתמשים במחלקה הזו, לא צריך להגדיר קבועים משלכם ל-URI של תוכן, לשמות של טבלאות או לעמודות. כדי להשתמש במחלקה הזו, צריך לכלול את ההצהרה הבאה:

Kotlin

import android.provider.ContactsContract

Java

import android.provider.ContactsContract;

מכיוון שהקוד משתמש ב-CursorLoader כדי לאחזר נתונים מהספק, צריך לציין שהוא מטמיע את ממשק הטעינה LoaderManager.LoaderCallbacks. כדי לזהות איזה איש קשר המשתמש בוחר מרשימת תוצאות החיפוש, צריך להטמיע את ממשק המתאם AdapterView.OnItemClickListener. לדוגמה:

Kotlin

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

Java

...
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 {

הגדרת משתנים גלובליים

מגדירים משתנים גלובליים שמשמשים בחלקים אחרים של הקוד:

Kotlin

...
/*
 * 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

Java

    ...
    /*
     * 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 Lint ב-Android Studio. כדי להשבית את האזהרה הזו, צריך להוסיף את ההערה @SuppressLint("InlinedApi") לפני ההגדרה של FROM_COLUMNS.

מפעילים את המקטע

מפעילים את Fragment. מוסיפים את ה-constructor הריק והציבורי שנדרש על ידי מערכת Android, ומנפחים את ממשק המשתמש של האובייקט Fragment בשיטת הקריאה החוזרת onCreateView(). לדוגמה:

Kotlin

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

Java

    // 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 שמציג את אנשי הקשר, צריך להפעיל את Activity.findViewById() באמצעות הפעילות הראשית של Fragment. משתמשים ב-Context של פעילות ההורה כשמפעילים את setAdapter(). לדוגמה:

Kotlin

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

Java

    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 הנוכחי כרכיב click listener על ידי ציון שהמחלקה מטמיעה את AdapterView.OnItemClickListener, כפי שמוצג בקטע הגדרת Fragment שמציג את רשימת אנשי הקשר.

כדי להמשיך בהגדרת המאזין, צריך לקשר אותו אל ListView על ידי קריאה ל-method‏ setOnItemClickListener() ב-onActivityCreated(). לדוגמה:

Kotlin

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

Java

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

מכיוון שציינתם שה-Fragment הנוכחי הוא ה-OnItemClickListener של ה-ListView, עכשיו אתם צריכים להטמיע את ה-method הנדרשת שלו, onItemClick(), שמטפלת באירוע מסוג קליק. התהליך הזה מתואר בקטע הבא.

הגדרת תחזית

מגדירים קבוע שמכיל את העמודות שרוצים להחזיר מהשאילתה. כל פריט ב-ListView מציג את השם המוצג של איש הקשר, שמכיל את הצורה העיקרית של שם איש הקשר. ב-Android 3.0 (גרסת API‏ 11) ואילך, שם העמודה הזו הוא Contacts.DISPLAY_NAME_PRIMARY. בגרסאות קודמות, השם שלה הוא Contacts.DISPLAY_NAME.

העמודה Contacts._ID משמשת את תהליך הקישור SimpleCursorAdapter. ‫Contacts._ID ו-LOOKUP_KEY משמשים יחד כדי ליצור URI של תוכן לאיש הקשר שהמשתמש בוחר.

Kotlin

...
@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
)

Java

...
@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, כי האינדקסים זהים לסדר של שמות העמודות בהיטל. לדוגמה:

Kotlin

// 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

Java

// 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 זדונית. לדוגמה:

Kotlin

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

Java

    // 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()‎

בקטע הקודם הגדרתם את רכיב ה-click listener של הפריט ל-ListView. עכשיו מטמיעים את הפעולה של המאזין על ידי הגדרת ה-method‏ AdapterView.OnItemClickListener.onItemClick():

Kotlin

    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.
             */
        }
    }

Java

    @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.
         */
    }

מאתחלים את ה-loader

מכיוון שאתם משתמשים ב-CursorLoader כדי לאחזר נתונים, אתם צריכים להפעיל את ה-thread ברקע ומשתנים אחרים ששולטים באחזור אסינכרוני. מבצעים את האיניציאליזציה ב-onCreate(), כמו בדוגמה הבאה:

Kotlin

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)

Java

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 חדש מהשיטה. בשדה content URI, מזינים Contacts.CONTENT_URI. ה-URI הזה מתייחס לכל הטבלה, כמו בדוגמה הבאה:

Kotlin

    ...
    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()
    }

Java

    ...
    @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()‎

מטמיעים את ה-method‏ onLoadFinished() . מסגרת רכיב הטעינה קוראת ל- onLoadFinished() כשניהול אנשי הקשר מחזיר את תוצאות השאילתה. בשיטה הזו, מזינים את התוצאה Cursor ב-SimpleCursorAdapter. הפעולה הזו מעדכנת באופן אוטומטי את ListView עם תוצאות החיפוש:

Kotlin

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

Java

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

השיטה onLoaderReset() מופעלת כשמסגרת ה-loader מזהה שהתוצאה Cursor מכילה נתונים לא עדכניים. מוחקים את ההפניה של SimpleCursorAdapter ל-Cursor הקיים. אם לא תעשו את זה, מסגרת ה-loader לא תמחזר את ה-Cursor, מה שיגרום לדליפת זיכרון. לדוגמה:

Kotlin

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

Java

    @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()‎.
  • מאתחלים את ה-loader.
  • מטמיעים את onLoadFinished()‎ ואת onLoaderReset()‎.

בשלבים הבאים מוסבר איך להוסיף קוד כדי להתאים מחרוזת חיפוש לסוג מסוים של נתונים מפורטים ולהציג את התוצאות.

בחירת סוג הנתונים והטבלה

כדי לחפש סוג מסוים של נתוני פרטים, צריך לדעת את הערך של סוג ה-MIME המותאם אישית של סוג הנתונים. לכל סוג נתונים יש ערך ייחודי של סוג MIME שמוגדר על ידי קבוע CONTENT_ITEM_TYPE במחלקת המשנה של ContactsContract.CommonDataKinds שמשויכת לסוג הנתונים. למחלקות המשנה יש שמות שמציינים את סוג הנתונים שלהן. לדוגמה, מחלקת המשנה של נתוני אימייל היא ContactsContract.CommonDataKinds.Email, וסוג ה-MIME המותאם אישית של נתוני אימייל מוגדר על ידי הקבוע Email.CONTENT_ITEM_TYPE.

משתמשים בטבלה ContactsContract.Data כדי לחפש. כל הקבועים שדרושים לכם להקרנה, לסעיף הבחירה ולסדר המיון מוגדרים בטבלה הזו או עוברים אליה בירושה.

הגדרת תחזית

כדי להגדיר היטל, בוחרים עמודה אחת או יותר שמוגדרות ב-ContactsContract.Data או במחלקות שמהן היא יורשת. ניהול אנשי הקשר מבצע איחוד משתמע בין ContactsContract.Data לטבלאות אחרות לפני שהוא מחזיר שורות. לדוגמה:

Kotlin

@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
)

Java

    @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. תוחמים את הערך במירכאות בודדות על ידי שרשור של התו "'" (מירכאות בודדות) בתחילת הקבוע ובסופו. אחרת, הספק מפרש את הערך כשם של משתנה ולא כערך של מחרוזת. לא צריך להשתמש בפלייסהולדר לערך הזה, כי משתמשים בקבוע ולא בערך שהמשתמש סיפק.

לדוגמה:

Kotlin

/*
 * 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}'"

Java

    /*
     * 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 + "'";

בשלב הבא, מגדירים משתנים שיכילו את הארגומנט של הבחירה:

Kotlin

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

Java

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

הטמעה של onCreateLoader()‎

אחרי שציינתם את הנתונים שאתם רוצים ואת הדרך למצוא אותם, אתם צריכים להגדיר שאילתה בהטמעה של onCreateLoader(). מחזירים CursorLoader חדש מהשיטה הזו, ומשתמשים בהיטל, בביטוי הטקסט של הבחירה ובמערך הבחירה כארגומנטים. ל-URI של תוכן, משתמשים ב-Data.CONTENT_URI. לדוגמה:

Kotlin

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

Java

@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()‎.
  • מאתחלים את ה-loader.
  • מטמיעים את onLoadFinished()‎ ואת onLoaderReset()‎.

בשלבים הבאים מוסבר איך להוסיף קוד כדי להתאים מחרוזת חיפוש לכל סוג של נתונים ולהציג את התוצאות.

הסרת קריטריונים שמשפיעים על הבחירה

אל תגדירו את הקבועים של SELECTION או את המשתנה mSelectionArgs. הם לא משמשים לאחזור מהסוג הזה.

הטמעה של onCreateLoader()‎

מטמיעים את השיטה onCreateLoader(), שמחזירה CursorLoader חדש. לא צריך להמיר את מחרוזת החיפוש לתבנית, כי ניהול אנשי הקשר עושה את זה באופן אוטומטי. משתמשים ב-Contacts.CONTENT_FILTER_URI בתור ה-URI הבסיסי, ומוסיפים לו את מחרוזת החיפוש באמצעות קריאה ל-Uri.withAppendedPath(). השימוש ב-URI הזה מפעיל באופן אוטומטי חיפוש של כל סוג נתונים, כמו בדוגמה הבאה:

Kotlin

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

Java

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

קטעי הקוד האלה הם הבסיס לאפליקציה שמבצעת חיפוש רחב בניהול אנשי הקשר. השיטה הזו שימושית לאפליקציות שרוצות להטמיע פונקציונליות שדומה למסך רשימת אנשי הקשר של אפליקציית "אנשי קשר".