Android开发中如何通过ContactsContract仅获取联系人的名？

常见踩坑根因 #

• 表结构不匹配：ContactsContract.CommonDataKinds.StructuredName.GIVEN_NAME 是结构化姓名模块下的专属字段，存储在Data表中，本身不属于CommonDataKinds.Phone电话号码表的列。直接在Phone表的查询结果中取该字段，会出现列不存在的异常。
• 代码逻辑疏漏：部分实现误将 cursor.getColumnIndex() 返回的整数类型列索引值，直接赋值为联系人名称，最终表现为返回纯数字而非名称字符串。
• 数据关联缺失：结构化姓名与电话号码属于同一联系人（RawContact）下的不同数据行，没有做行ID关联的话，即使取到GIVEN_NAME的值，也无法和对应联系人匹配。

正确实现思路 #

• 调整查询数据源：统一从 ContactsContract.Data.CONTENT_URI 拉取数据，通过MIME类型匹配需要的结构化姓名数据行，不再直接依赖Phone表查询。
• 增加列有效性校验：取值前先判断列索引是否为有效非负值，避免因为列不存在触发逻辑错误。
• 按需做数据关联：如果业务需要同时拿到联系人的名和绑定的电话号码，通过RawContact ID对不同类型的数据行做合并即可。

代码示例1：仅批量获取所有联系人的名（无需读取电话号码）

// 查询投影：仅需要取GIVEN_NAME字段
val projection = arrayOf(
    ContactsContract.CommonDataKinds.StructuredName.GIVEN_NAME
)
// 过滤规则：只匹配结构化姓名类型的数据行
val selection = "${ContactsContract.Data.MIMETYPE} = ?"
val selectionArgs = arrayOf(
    ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE
)
contentResolver.query(
    ContactsContract.Data.CONTENT_URI,
    projection,
    selection,
    selectionArgs,
    null
)?.use { cursor ->
    val givenNameColumnIndex = cursor.getColumnIndex(ContactsContract.CommonDataKinds.StructuredName.GIVEN_NAME)
    // 列无效直接跳过
    if (givenNameColumnIndex < 0) return@use
    while (cursor.moveToNext()) {
        val givenName = cursor.getString(givenNameColumnIndex)
        // 对单个联系人的名做业务处理
    }
}

代码示例2：同时获取联系人的名与绑定的电话号码

val projection = arrayOf(
    ContactsContract.RawContacts._ID,
    ContactsContract.Data.MIMETYPE,
    ContactsContract.CommonDataKinds.StructuredName.GIVEN_NAME,
    ContactsContract.CommonDataKinds.Phone.NUMBER
)
// 同时匹配结构化姓名、电话号码两类数据行
val selection = "${ContactsContract.Data.MIMETYPE} IN (?, ?)"
val selectionArgs = arrayOf(
    ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE,
    ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
)
contentResolver.query(
    ContactsContract.Data.CONTENT_URI,
    projection,
    selection,
    selectionArgs,
    null
)?.use { cursor ->
    // 提前缓存列索引，避免循环内重复查询
    val rawIdIndex = cursor.getColumnIndex(ContactsContract.RawContacts._ID)
    val mimeTypeIndex = cursor.getColumnIndex(ContactsContract.Data.MIMETYPE)
    val givenNameIndex = cursor.getColumnIndex(ContactsContract.CommonDataKinds.StructuredName.GIVEN_NAME)
    val phoneNumIndex = cursor.getColumnIndex(ContactsContract.CommonDataKinds.Phone.NUMBER)
    // 按RawContact ID做数据合并
    val contactDataMap = mutableMapOf<Long, Pair<String, String>>()

    while (cursor.moveToNext()) {
        val rawId = cursor.getLong(rawIdIndex)
        when (cursor.getString(mimeTypeIndex)) {
            // 读到结构化姓名行，存入映射表
            ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE -> {
                val givenName = if (givenNameIndex >= 0) cursor.getString(givenNameIndex) else ""
                val existingPhone = contactDataMap[rawId]?.second ?: ""
                contactDataMap[rawId] = givenName to existingPhone
            }
            // 读到电话号码行，和已有的名做合并
            ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE -> {
                val phoneNum = if (phoneNumIndex >=0) cursor.getString(phoneNumIndex) else ""
                val existingName = contactDataMap[rawId]?.first ?: ""
                contactDataMap[rawId] = existingName to phoneNum
            }
        }
    }
}

异常场景兜底处理 #

• 当联系人未录入结构化姓名时，GIVEN_NAME字段会返回空值，可以增加兜底逻辑：从完整显示名DISPLAY_NAME中按系统姓名排序规则拆分第一段，作为临时的名展示。
• 查询前需确认已获取android.permission.READ_CONTACTS运行时权限，否则会返回空Cursor导致逻辑异常。

内容的提问来源于stack exchange，提问作者UyerBit