本课程介绍如何检索联系人的详细数据,例如电子邮件地址、电话号码等。这些是用户在检索联系人时所需了解的详细信息。您可以向他们提供联系人的所有详细信息,或者仅显示特定类型的详细信息,例如电子邮件地址。
本课程中的步骤假定您已拥有用户所选联系人的 ContactsContract.Contacts
行。 “检索联系人姓名”课程介绍了如何检索联系人列表。
检索联系人的所有详细信息
要检索联系人的所有详细信息,请在 ContactsContract.Data
表中搜索包含联系人 LOOKUP_KEY
的所有行。此列在 ContactsContract.Data
表中可用,因为联系人提供方在 ContactsContract.Contacts
表和 ContactsContract.Data
表之间进行了隐式联接。LOOKUP_KEY
列在“检索联系人姓名”课程中进行了更详细的描述。
注意:检索联系人的所有详细信息会降低设备的性能,因为它需要检索 ContactsContract.Data
表中的所有列。在使用此技术之前,请考虑其性能影响。
请求权限
要从联系人提供方读取数据,您的应用必须具有 READ_CONTACTS
权限。要请求此权限,请将以下 <manifest>
的子元素添加到您的 manifest 文件中
<uses-permission android:name="android.permission.READ_CONTACTS" />
设置投影
根据行包含的数据类型,它可能只使用少数列或许多列。此外,数据也根据数据类型位于不同的列中。为确保您获取所有可能数据类型的所有可能列,您需要将所有列名添加到您的投影中。如果您要将结果 Cursor
绑定到 ListView
,请始终检索 Data._ID
;否则,绑定将不起作用。同时检索 Data.MIMETYPE
,以便您可以识别检索到的每一行的数据类型。例如
Kotlin
private val PROJECTION: Array<out String> = arrayOf( ContactsContract.Data._ID, ContactsContract.Data.MIMETYPE, ContactsContract.Data.DATA1, ContactsContract.Data.DATA2, ContactsContract.Data.DATA3, ContactsContract.Data.DATA4, ContactsContract.Data.DATA5, ContactsContract.Data.DATA6, ContactsContract.Data.DATA7, ContactsContract.Data.DATA8, ContactsContract.Data.DATA9, ContactsContract.Data.DATA10, ContactsContract.Data.DATA11, ContactsContract.Data.DATA12, ContactsContract.Data.DATA13, ContactsContract.Data.DATA14, ContactsContract.Data.DATA15 )
Java
private static final String[] PROJECTION = { ContactsContract.Data._ID, ContactsContract.Data.MIMETYPE, ContactsContract.Data.DATA1, ContactsContract.Data.DATA2, ContactsContract.Data.DATA3, ContactsContract.Data.DATA4, ContactsContract.Data.DATA5, ContactsContract.Data.DATA6, ContactsContract.Data.DATA7, ContactsContract.Data.DATA8, ContactsContract.Data.DATA9, ContactsContract.Data.DATA10, ContactsContract.Data.DATA11, ContactsContract.Data.DATA12, ContactsContract.Data.DATA13, ContactsContract.Data.DATA14, ContactsContract.Data.DATA15 };
此投影检索 ContactsContract.Data
表中行的所有列,使用 ContactsContract.Data
类中定义的列名。
或者,您也可以使用 ContactsContract.Data
类中定义或继承的任何其他列常量。但是请注意,SYNC1
到 SYNC4
列旨在由同步适配器使用,因此它们的数据没有用处。
定义选择条件
定义用于选择子句的常量、用于存储选择参数的数组以及用于存储选择值的变量。使用 Contacts.LOOKUP_KEY
列查找联系人。例如
Kotlin
// Defines the selection clause private const val SELECTION: String = "${ContactsContract.Data.LOOKUP_KEY} = ?" ... // Defines the array to hold the search criteria private val selectionArgs: Array<String> = arrayOf("") /* * Defines a variable to contain the selection value. Once you * have the Cursor from the Contacts table, and you've selected * the desired row, move the row's LOOKUP_KEY value into this * variable. */ private var lookupKey: String? = null
Java
// Defines the selection clause private static final String SELECTION = Data.LOOKUP_KEY + " = ?"; // Defines the array to hold the search criteria private String[] selectionArgs = { "" }; /* * Defines a variable to contain the selection value. Once you * have the Cursor from the Contacts table, and you've selected * the desired row, move the row's LOOKUP_KEY value into this * variable. */ private lateinit var lookupKey: String
在您的选择文本表达式中使用 "?" 作为占位符可确保生成的搜索是通过绑定而非 SQL 编译生成的。这种方法消除了恶意 SQL 注入的可能性。
定义排序顺序
定义您希望在结果 Cursor
中使用的排序顺序。为了将特定数据类型的所有行保持在一起,请按 Data.MIMETYPE
排序。此查询参数将所有电子邮件行、所有电话行等分组在一起。例如
Kotlin
/* * Defines a string that specifies a sort order of MIME type */ private const val SORT_ORDER = ContactsContract.Data.MIMETYPE
Java
/* * Defines a string that specifies a sort order of MIME type */ private static final String SORT_ORDER = ContactsContract.Data.MIMETYPE;
注意:某些数据类型不使用子类型,因此您无法按子类型排序。相反,您必须遍历返回的 Cursor
,确定当前行的数据类型,并存储使用子类型的行的数据。读取完游标后,您可以按子类型对每种数据类型进行排序并显示结果。
初始化加载器
始终在后台线程中从联系人提供方(以及所有其他内容提供方)执行检索。使用由 LoaderManager
类和 LoaderManager.LoaderCallbacks
接口定义的 Loader 框架执行后台检索。
当您准备好检索行时,通过调用 initLoader()
初始化 loader 框架。将整数标识符传递给该方法;此标识符将传递给 LoaderManager.LoaderCallbacks
方法。此标识符通过允许您区分不同的 loader 来帮助您在应用中使用多个 loader。
以下代码段展示了如何初始化 loader 框架
Kotlin
// Defines a constant that identifies the loader private const val DETAILS_QUERY_ID: Int = 0 class DetailsFragment : Fragment(), LoaderManager.LoaderCallbacks<Cursor> { ... override fun onCreate(savedInstanceState: Bundle?) { ... // Initializes the loader framework loaderManager.initLoader(DETAILS_QUERY_ID, null, this)
Java
public class DetailsFragment extends Fragment implements LoaderManager.LoaderCallbacks<Cursor> { ... // Defines a constant that identifies the loader static int DETAILS_QUERY_ID = 0; ... @Override public void onCreate(Bundle savedInstanceState) { ... // Initializes the loader framework getLoaderManager().initLoader(DETAILS_QUERY_ID, null, this);
实现 onCreateLoader()
实现 onCreateLoader()
方法,该方法在您调用 initLoader()
后立即由 loader 框架调用。从此方法返回一个 CursorLoader
。由于您正在搜索 ContactsContract.Data
表,因此请使用常量 Data.CONTENT_URI
作为内容 URI。例如
Kotlin
override fun onCreateLoader(loaderId: Int, args: Bundle?): Loader<Cursor> { // Choose the proper action mLoader = when(loaderId) { DETAILS_QUERY_ID -> { // Assigns the selection parameter selectionArgs[0] = lookupKey // Starts the query activity?.let { CursorLoader( it, ContactsContract.Data.CONTENT_URI, PROJECTION, SELECTION, selectionArgs, SORT_ORDER ) } } ... } return mLoader }
Java
@Override public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) { // Choose the proper action switch (loaderId) { case DETAILS_QUERY_ID: // Assigns the selection parameter selectionArgs[0] = lookupKey; // Starts the query CursorLoader mLoader = new CursorLoader( getActivity(), ContactsContract.Data.CONTENT_URI, PROJECTION, SELECTION, selectionArgs, SORT_ORDER ); }
实现 onLoadFinished() 和 onLoaderReset()
实现 onLoadFinished()
方法。当联系人提供方返回查询结果时,loader 框架会调用 onLoadFinished()
。例如
Kotlin
override fun onLoadFinished(loader: Loader<Cursor>, data: Cursor) { when(loader.id) { DETAILS_QUERY_ID -> { /* * Process the resulting Cursor here. */ } ... } }
Java
@Override public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) { switch (loader.getId()) { case DETAILS_QUERY_ID: /* * Process the resulting Cursor here. */ } break; ... } }
当 loader 框架检测到支持结果 Cursor
的数据已更改时,会调用 onLoaderReset()
方法。此时,通过将任何现有对 Cursor
的引用设置为 null 来移除它们。否则,loader 框架将不会销毁旧的 Cursor
,并且会导致内存泄漏。例如
Kotlin
override fun onLoaderReset(loader: Loader<Cursor>) { when (loader.id) { DETAILS_QUERY_ID -> { /* * If you have current references to the Cursor, * remove them here. */ } ... } }
Java
@Override public void onLoaderReset(Loader<Cursor> loader) { switch (loader.getId()) { case DETAILS_QUERY_ID: /* * If you have current references to the Cursor, * remove them here. */ } break; }
检索联系人的特定详细信息
检索联系人的特定数据类型(例如所有电子邮件)与检索所有详细信息的模式相同。您只需要对 检索联系人的所有详细信息 中列出的代码进行以下更改
- 投影
- 修改您的投影以检索特定于数据类型的列。同时修改投影以使用
ContactsContract.CommonDataKinds
中与数据类型对应的子类中定义的列名常量。 - 选择
- 修改选择文本以搜索特定于您的数据类型的
MIMETYPE
值。 - 排序顺序
- 由于您只选择了一种详细信息类型,请不要按
Data.MIMETYPE
对返回的Cursor
进行分组。
这些修改将在以下部分进行描述。
定义投影
使用 ContactsContract.CommonDataKinds
中与数据类型对应的子类中的列名常量,定义要检索的列。如果您打算将 Cursor
绑定到 ListView
,请务必检索 _ID
列。例如,要检索电子邮件数据,请定义以下投影
Kotlin
private val PROJECTION: Array<String> = arrayOf( ContactsContract.CommonDataKinds.Email._ID, ContactsContract.CommonDataKinds.Email.ADDRESS, ContactsContract.CommonDataKinds.Email.TYPE, ContactsContract.CommonDataKinds.Email.LABEL )
Java
private static final String[] PROJECTION = { ContactsContract.CommonDataKinds.Email._ID, ContactsContract.CommonDataKinds.Email.ADDRESS, ContactsContract.CommonDataKinds.Email.TYPE, ContactsContract.CommonDataKinds.Email.LABEL };
请注意,此投影使用了 ContactsContract.CommonDataKinds.Email
类中定义的列名,而不是 ContactsContract.Data
类中定义的列名。使用电子邮件特定的列名可以使代码更易读。
在投影中,您也可以使用 ContactsContract.CommonDataKinds
子类中定义的任何其他列。
定义选择条件
定义搜索文本表达式,该表达式检索特定联系人的 LOOKUP_KEY
和您所需详细信息的 Data.MIMETYPE
值所对应的行。通过在常量开头和结尾连接一个 "'
"(单引号)字符,将 MIMETYPE
值括在单引号中;否则,提供方会将常量解释为变量名而非字符串值。您无需为此值使用占位符,因为您使用的是常量而非用户提供的值。例如
Kotlin
/* * Defines the selection clause. Search for a lookup key * and the Email MIME type */ private const val SELECTION = "${ContactsContract.Data.LOOKUP_KEY} = ? AND " + "${ContactsContract.Data.MIMETYPE} = '${Email.CONTENT_ITEM_TYPE}'" ... // Defines the array to hold the search criteria private val selectionArgs: Array<String> = arrayOf("")
Java
/* * Defines the selection clause. Search for a lookup key * and the Email MIME type */ private static final String SELECTION = Data.LOOKUP_KEY + " = ?" + " AND " + Data.MIMETYPE + " = " + "'" + Email.CONTENT_ITEM_TYPE + "'"; // Defines the array to hold the search criteria private String[] selectionArgs = { "" };
定义排序顺序
定义返回的 Cursor
的排序顺序。由于您正在检索特定数据类型,因此请省略按 MIMETYPE
排序。相反,如果您搜索的详细数据类型包含子类型,请按子类型排序。例如,对于电子邮件数据,您可以按 Email.TYPE
排序
Kotlin
private const val SORT_ORDER: String = "${Email.TYPE} ASC"
Java
private static final String SORT_ORDER = Email.TYPE + " ASC ";