Pobieranie listy kontaktów

Z tej lekcji dowiesz się, jak pobrać listę kontaktów, których dane pasują do całości lub części wyszukiwanego ciągu znaków, za pomocą tych technik:

Dopasowywanie nazw kontaktów
Pobierz listę kontaktów, dopasowując wyszukiwany ciąg znaków do całości lub części danych nazwy kontaktu. Dostawca kontaktów zezwala na wiele wystąpień tej samej nazwy, więc ta technika może zwrócić listę dopasowań.
dopasowywanie określonego typu danych, np. numeru telefonu;
Pobierz listę kontaktów, dopasowując wyszukiwany ciąg znaków do określonego typu danych, takich jak adres e-mail. Ta technika pozwala na przykład wyświetlić listę wszystkich kontaktów, których adres e-mail pasuje do wyszukiwanego ciągu znaków.
Dopasuj dowolny typ danych
Pobierz listę kontaktów, dopasowując wyszukiwany ciąg znaków do dowolnego typu danych szczegółowych, w tym imienia i nazwiska, numeru telefonu, adresu, adresu e-mail itp. Ta technika pozwala na przykład zaakceptować dowolny typ danych dla ciągu wyszukiwania, a następnie wyświetlić listę kontaktów, dla których dane pasują do ciągu.

Uwaga: wszystkie przykłady w tej lekcji używają CursorLoader do pobierania danych od dostawcy kontaktów. CursorLoader uruchamia zapytanie w wątku, który jest oddzielony od wątku UI. Dzięki temu zapytanie nie spowalnia czasu odpowiedzi interfejsu i nie powoduje pogorszenia wrażeń użytkownika. Więcej informacji znajdziesz w szkoleniu na temat Androida Wczytywanie danych w tle.

Poproś o uprawnienia do odczytu dostawcy

Aby przeprowadzić dowolny rodzaj wyszukiwania w dostawcy kontaktów, aplikacja musi mieć uprawnienie READ_CONTACTS. Aby o to poprosić, dodaj element <uses-permission> do pliku manifestu jako element podrzędny elementu <manifest>:

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

Dopasowywanie kontaktu według nazwy i wyświetlanie wyników

Ta technika próbuje dopasować wyszukiwany ciąg znaków do nazwy kontaktu lub kontaktów w tabeli ContactsContract.Contacts dostawcy kontaktów. Zwykle wyniki wyświetla się w obiekcie ListView, aby użytkownik mógł wybrać odpowiedni kontakt.

Definiowanie układów ListView i elementów

Aby wyświetlić wyniki wyszukiwania w komponencie ListView, potrzebujesz głównego pliku układu, który definiuje cały interfejs, w tym komponent ListView, oraz pliku układu elementu, który definiuje 1 wiersz komponentu ListView. Możesz na przykład utworzyć główny plik układu res/layout/contacts_list_view.xml z tym kodem 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"/>

Ten kod XML używa wbudowanego widżetu Androida ListView android:id/list.

Zdefiniuj plik układu elementu contacts_list_item.xml za pomocą tego kodu 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"/>

Ten kod XML używa wbudowanego widżetu Androida TextView android:text1.

Uwaga: ta lekcja nie opisuje interfejsu do pobierania ciągu wyszukiwania od użytkownika, ponieważ możesz chcieć pobrać ciąg pośrednio. Możesz na przykład dać użytkownikowi możliwość wyszukiwania kontaktów, których nazwa pasuje do ciągu znaków w przychodzącej wiadomości tekstowej.

2 utworzone przez Ciebie pliki układu definiują interfejs użytkownika, który wyświetla ListView. Następnym krokiem jest napisanie kodu, który używa tego interfejsu do wyświetlania listy kontaktów.

Definiowanie fragmentu wyświetlającego listę kontaktów

Aby wyświetlić listę kontaktów, zacznij od zdefiniowania elementu Fragment, który jest wczytywany przez element Activity. Użycie Fragment jest bardziej elastyczną techniką, ponieważ możesz użyć jednego Fragment do wyświetlenia listy i drugiego Fragment do wyświetlenia szczegółów kontaktu wybranego przez użytkownika z listy. Korzystając z tego podejścia, możesz połączyć jedną z technik przedstawionych w tej lekcji z techniką z lekcji Pobieranie szczegółowych informacji o kontakcie.

Aby dowiedzieć się, jak używać co najmniej 1 obiektu Fragment z Activity, przeczytaj szkolenie Tworzenie dynamicznego interfejsu za pomocą fragmentów.

Aby ułatwić pisanie zapytań do dostawcy kontaktów, platforma Androida udostępnia klasę kontraktową o nazwie ContactsContract, która definiuje przydatne stałe i metody dostępu do dostawcy. Gdy używasz tej klasy, nie musisz definiować własnych stałych dla identyfikatorów URI treści, nazw tabel ani kolumn. Aby użyć tej klasy, dołącz to oświadczenie:

Kotlin

import android.provider.ContactsContract

Java

import android.provider.ContactsContract;

Ponieważ kod używa CursorLoader do pobierania danych od dostawcy, musisz określić, że implementuje on interfejs modułu ładującego LoaderManager.LoaderCallbacks. Aby ułatwić wykrywanie, który kontakt użytkownik wybiera z listy wyników wyszukiwania, zaimplementuj interfejs adaptera AdapterView.OnItemClickListener. Na przykład:

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 {

Definiowanie zmiennych globalnych

Zdefiniuj zmienne globalne, które są używane w innych częściach kodu:

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

Uwaga: ponieważ Contacts.DISPLAY_NAME_PRIMARY wymaga Androida 3.0 (interfejs API w wersji 11) lub nowszego, ustawienie minSdkVersion aplikacji na 10 lub mniej spowoduje wygenerowanie ostrzeżenia Android Lint w Android Studio. Aby wyłączyć to ostrzeżenie, dodaj adnotację @SuppressLint("InlinedApi") przed definicją FROM_COLUMNS.

Inicjowanie fragmentu

Zainicjuj Fragment. Dodaj pusty, publiczny konstruktor wymagany przez system Android i wywołaj UI obiektu Fragment w metodzie wywołania zwrotnego onCreateView(). Na przykład:

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

Konfigurowanie adaptera CursorAdapter dla widoku ListView

Skonfiguruj SimpleCursorAdapter, który wiąże wyniki wyszukiwania z ListView. Aby uzyskać obiekt ListView, który wyświetla kontakty, musisz wywołać Activity.findViewById(), używając aktywności nadrzędnej Fragment. Podczas wywoływania setAdapter() użyj Context aktywności nadrzędnej. Na przykład:

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

Ustawianie detektora wybranego kontaktu

Gdy wyświetlasz wyniki wyszukiwania, zwykle chcesz umożliwić użytkownikowi wybranie pojedynczego kontaktu do dalszego przetwarzania. Na przykład gdy użytkownik kliknie kontakt, możesz wyświetlić adres kontaktu na mapie. Aby udostępnić tę funkcję, najpierw zdefiniuj bieżący obiekt Fragment jako detektor kliknięć, określając, że klasa implementuje interfejs AdapterView.OnItemClickListener, jak pokazano w sekcji Definiowanie fragmentu wyświetlającego listę kontaktów.

Aby kontynuować konfigurowanie detektora, powiąż go z ListView, wywołując metodę setOnItemClickListener() w onActivityCreated(). Na przykład:

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

Ponieważ określono, że bieżący Fragment jest OnItemClickListener dla ListView, musisz teraz zaimplementować wymaganą metodę onItemClick(), która obsługuje zdarzenie kliknięcia. Zostało to opisane w następnej sekcji.

Definiowanie projekcji

Zdefiniuj stałą zawierającą kolumny, które chcesz zwrócić z zapytania. Każdy element w ListView zawiera wyświetlaną nazwę kontaktu, która zawiera główną formę nazwy kontaktu. W Androidzie 3.0 (API w wersji 11) i nowszych ta kolumna nazywa się Contacts.DISPLAY_NAME_PRIMARY, a we wcześniejszych wersjach – Contacts.DISPLAY_NAME.

Kolumna Contacts._ID jest używana przez proces wiązania SimpleCursorAdapter. Contacts._ID i LOOKUP_KEY są używane razem do utworzenia identyfikatora URI treści dla kontaktu wybranego przez użytkownika.

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

        };

Zdefiniuj stałe dla indeksów kolumn kursora

Aby pobrać dane z pojedynczej kolumny w Cursor, musisz znać indeks kolumny w Cursor. Możesz zdefiniować stałe dla indeksów kolumn Cursor, ponieważ indeksy są takie same jak kolejność nazw kolumn w projekcji. Na przykład:

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;

Określanie kryteriów wyboru

Aby określić dane, które chcesz znaleźć, utwórz kombinację wyrażeń tekstowych i zmiennych, które wskażą dostawcy kolumny danych do przeszukania i wartości do znalezienia.

W przypadku wyrażenia tekstowego zdefiniuj stałą, która zawiera listę kolumn wyszukiwania. Chociaż to wyrażenie może też zawierać wartości, zalecaną praktyką jest reprezentowanie wartości za pomocą obiektu zastępczego „?”. Podczas pobierania obiekt zastępczy jest zastępowany wartościami z tablicy. Użycie znaku „?” jako obiektu zastępczego gwarantuje, że specyfikacja wyszukiwania zostanie wygenerowana przez powiązanie, a nie przez kompilację SQL. Ta praktyka eliminuje możliwość wstrzyknięcia złośliwego kodu SQL. Na przykład:

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

Definiowanie metody onItemClick()

W poprzedniej sekcji ustawiono detektor kliknięć elementu dla ListView. Teraz zaimplementuj działanie dla detektora, definiując metodę 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.
         */
    }

Inicjowanie modułu ładującego

Do pobierania danych używasz CursorLoader, więc musisz zainicjować wątek w tle i inne zmienne, które kontrolują asynchroniczne pobieranie. Wykonaj inicjowanie w onCreate(), jak w tym przykładzie:

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

Implementacja onCreateLoader()

Zaimplementuj metodę onCreateLoader(), która jest wywoływana przez platformę modułu ładującego natychmiast po wywołaniu metody initLoader().

W onCreateLoader() skonfiguruj wzorzec ciągu wyszukiwania. Aby przekształcić ciąg znaków we wzorzec, wstaw znaki „%” (procent), które reprezentują sekwencję składającą się z co najmniej 0 znaków, lub znaki „_” (podkreślenie), które reprezentują pojedynczy znak, albo oba te znaki. Na przykład wzorzec „%Jefferson%” będzie pasować zarówno do „Thomas Jefferson”, jak i „Jefferson Davis”.

Zwróć nowy obiekt CursorLoader z metody. Jako identyfikator URI treści użyj Contacts.CONTENT_URI. Ten identyfikator URI odnosi się do całej tabeli, jak pokazano w tym przykładzie:

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

Implementowanie metod onLoadFinished() i onLoaderReset()

Zaimplementuj metodę onLoadFinished(). Gdy dostawca kontaktów zwraca wyniki zapytania, platforma modułu ładującego wywołuje metodę onLoadFinished(). W tej metodzie umieść wynik Cursor w SimpleCursorAdapter. Spowoduje to automatyczne zaktualizowanie ListView o wyniki wyszukiwania:

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

Metoda onLoaderReset() jest wywoływana, gdy platforma modułu ładującego wykryje, że wynik Cursor zawiera nieaktualne dane. Usuń odwołanie SimpleCursorAdapter do istniejącego elementu Cursor. Jeśli tego nie zrobisz, platforma modułu ładującego nie będzie ponownie wykorzystywać Cursor, co spowoduje wyciek pamięci. Na przykład:

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

    }

Masz teraz kluczowe elementy aplikacji, która dopasowuje ciąg wyszukiwania do nazw kontaktów i zwraca wynik w komponencie ListView. Użytkownik może kliknąć nazwę kontaktu, aby go wybrać. Spowoduje to uruchomienie detektora, w którym możesz dalej pracować z danymi kontaktu. Możesz na przykład pobrać dane kontaktu. Aby dowiedzieć się, jak to zrobić, przejdź do następnej lekcji: Pobieranie szczegółowych informacji o kontakcie.

Więcej informacji o interfejsach wyszukiwarki znajdziesz w przewodniku po interfejsie API Tworzenie interfejsu wyszukiwarki.

W pozostałych sekcjach tej lekcji przedstawiono inne sposoby znajdowania kontaktów u dostawcy kontaktów.

Dopasowywanie kontaktu według określonego typu danych

Ta technika pozwala określić typ danych, które chcesz dopasować. Pobieranie według nazwy to konkretny przykład tego typu zapytania, ale możesz też wyszukiwać według dowolnego typu danych szczegółowych powiązanych z kontaktem. Możesz na przykład pobrać kontakty, które mają określony kod pocztowy. W takim przypadku wyszukiwany ciąg znaków musi pasować do danych przechowywanych w wierszu kodu pocztowego.

Aby wdrożyć ten typ pobierania, najpierw zaimplementuj ten kod, jak opisano w poprzednich sekcjach:

  • Poproś o uprawnienia do odczytu dostawcy.
  • Zdefiniuj układy ListView i elementów.
  • Zdefiniuj fragment, który wyświetla listę kontaktów.
  • Zdefiniuj zmienne globalne.
  • Zainicjuj fragment.
  • Skonfiguruj CursorAdapter dla ListView.
  • Ustaw detektor wybranego kontaktu.
  • Zdefiniuj stałe dla indeksów kolumn kursora.

    Chociaż pobierasz dane z innej tabeli, kolejność kolumn w projekcji jest taka sama, więc możesz używać tych samych indeksów dla kursora.

  • Zdefiniuj metodę onItemClick().
  • Zainicjuj moduł ładowania.
  • Zaimplementuj metody onLoadFinished() i onLoaderReset().

Poniższe kroki pokazują dodatkowy kod, który jest potrzebny, aby dopasować ciąg wyszukiwania do określonego typu danych szczegółowych i wyświetlić wyniki.

Wybór typu danych i tabeli

Aby wyszukać określony typ danych szczegółowych, musisz znać wartość niestandardowego typu MIME dla danego typu danych. Każdy typ danych ma unikalną wartość typu MIME zdefiniowaną przez stałą CONTENT_ITEM_TYPE w podklasie ContactsContract.CommonDataKinds powiązanej z typem danych. Nazwy podklas wskazują typ danych, np. podklasa danych e-mail to ContactsContract.CommonDataKinds.Email, a niestandardowy typ MIME dla danych e-mail jest definiowany przez stałą Email.CONTENT_ITEM_TYPE.

Do wyszukiwania użyj tabeli ContactsContract.Data. Wszystkie stałe potrzebne do projekcji, klauzuli wyboru i kolejności sortowania są zdefiniowane w tej tabeli lub przez nią dziedziczone.

Definiowanie projekcji

Aby zdefiniować projekcję, wybierz co najmniej 1 kolumnę zdefiniowaną w ContactsContract.Data lub klasy, z których dziedziczy. Zanim dostawca kontaktów zwróci wiersze, wykonuje niejawne złączenie między ContactsContract.Data i innymi tabelami. Na przykład:

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

Definiowanie kryteriów wyszukiwania

Aby wyszukać ciąg znaków w określonym typie danych, utwórz klauzulę wyboru z tych elementów:

  • Nazwa kolumny zawierającej wyszukiwany ciąg znaków. Ta nazwa różni się w zależności od typu danych, więc musisz znaleźć podklasę ContactsContract.CommonDataKinds, która odpowiada typowi danych, a następnie wybrać nazwę kolumny z tej podklasy. Aby na przykład wyszukać adresy e-mail, użyj kolumny Email.ADDRESS.
  • Sam ciąg wyszukiwania, reprezentowany przez znak „?” w klauzuli wyboru.
  • Nazwa kolumny zawierającej wartość niestandardowego typu MIME. Ta nazwa to zawsze Data.MIMETYPE.
  • Wartość niestandardowego typu MIME dla typu danych. Jak opisano wcześniej, jest to stała CONTENT_ITEM_TYPE w podklasie ContactsContract.CommonDataKinds. Na przykład wartość typu MIME dla danych e-mail to Email.CONTENT_ITEM_TYPE. Ujmij wartość w pojedyncze cudzysłowy, dodając znak „'” (pojedynczy cudzysłów) na początku i na końcu stałej. W przeciwnym razie dostawca zinterpretuje wartość jako nazwę zmiennej, a nie jako wartość ciągu znaków. Nie musisz używać obiektu zastępczego dla tej wartości, ponieważ używasz stałej, a nie wartości podanej przez użytkownika.

Na przykład:

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

Następnie zdefiniuj zmienne, które będą zawierać argument wyboru:

Kotlin

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

Java

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

Implementacja onCreateLoader()

Teraz, gdy masz już określone dane, które chcesz znaleźć, i sposób ich wyszukiwania, zdefiniuj zapytanie w swojej implementacji onCreateLoader(). Zwróć nowy obiekt CursorLoader z tej metody, używając projekcji, wyrażenia tekstowego wyboru i tablicy wyboru jako argumentów. W przypadku identyfikatora URI treści użyj Data.CONTENT_URI. Na przykład:

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

Te fragmenty kodu stanowią podstawę podstawowego wyszukiwania wstecznego na podstawie określonego typu danych szczegółowych. To najlepsza technika, jeśli aplikacja koncentruje się na określonym typie danych, np. e-mailach, i chcesz umożliwić użytkownikom uzyskiwanie nazw powiązanych z danymi.

Dopasowywanie kontaktu na podstawie dowolnego typu danych

Pobieranie kontaktu na podstawie dowolnego typu danych zwraca kontakty, jeśli którekolwiek z ich danych pasują do ciągu wyszukiwania, w tym imię i nazwisko, adres e-mail, adres pocztowy, numer telefonu itp. Dzięki temu uzyskasz szeroki zakres wyników wyszukiwania. Jeśli na przykład wyszukiwany ciąg to „Kowalski”, wyszukiwanie dowolnego typu danych zwróci kontakt „Jan Kowalski”, ale też kontakty, które mieszkają na „ulicy Kowalskiego”.

Aby wdrożyć ten typ pobierania, najpierw zaimplementuj ten kod, jak opisano w poprzednich sekcjach:

  • Poproś o uprawnienia do odczytu dostawcy.
  • Zdefiniuj układy ListView i elementów.
  • Zdefiniuj fragment, który wyświetla listę kontaktów.
  • Zdefiniuj zmienne globalne.
  • Zainicjuj fragment.
  • Skonfiguruj CursorAdapter dla ListView.
  • Ustaw detektor wybranego kontaktu.
  • Zdefiniuj projekcję.
  • Zdefiniuj stałe dla indeksów kolumn kursora.

    W przypadku tego typu pobierania używasz tej samej tabeli co w sekcji Dopasowywanie kontaktu według nazwy i wyświetlanie wyników. Użyj też tych samych indeksów kolumn.

  • Zdefiniuj metodę onItemClick().
  • Zainicjuj moduł ładowania.
  • Zaimplementuj metody onLoadFinished() i onLoaderReset().

Poniższe kroki pokazują dodatkowy kod, który jest potrzebny do dopasowania ciągu wyszukiwania do dowolnego typu danych i wyświetlenia wyników.

Usuwanie kryteriów wyboru

Nie definiuj stałych SELECTION ani zmiennej mSelectionArgs. Nie są one używane w tym typie pobierania.

Implementacja onCreateLoader()

Zaimplementuj metodę onCreateLoader(), zwracając nowy obiekt CursorLoader. Nie musisz przekształcać ciągu wyszukiwania we wzorzec, ponieważ dostawca kontaktów robi to automatycznie. Użyj Contacts.CONTENT_FILTER_URI jako podstawowego identyfikatora URI i dołącz do niego ciąg wyszukiwania, wywołując Uri.withAppendedPath(). Użycie tego identyfikatora URI automatycznie powoduje wyszukiwanie dowolnego typu danych, jak pokazano w tym przykładzie:

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

Te fragmenty kodu stanowią podstawę aplikacji, która przeprowadza szerokie wyszukiwanie w dostawcy kontaktów. Ta technika jest przydatna w przypadku aplikacji, które chcą wdrożyć funkcje podobne do ekranu listy kontaktów w aplikacji Kontakty.