本文详解在 android 应用中通过 contactscontract api 安全、可靠地读取指定联系人手机号的完整实现方案，涵盖权限配置、uri 构建、多级查询逻辑及常见错误排查。
本文详解在 android 应用中通过 contactscontract api 安全、可靠地读取指定联系人手机号的完整实现方案，涵盖权限配置、uri 构建、多级查询逻辑及常见错误排查。
在 Android 中读取联系人电话号码是一个看似简单却极易出错的操作——许多开发者会发现 ContactsContract.CommonDataKinds.Phone.NUMBER 字段始终返回 -1（即列索引未找到），日志显示 cursor.getColumnNames() 中完全不包含 data1（即 NUMBER 对应的实际列名），甚至 getString(phoneNumberIndex) 直接抛出 CursorWindow.nativeGetString 异常。根本原因在于：你正在对联系人主表（ContactsContract.Contacts）的 URI 发起查询，但该 URI 仅返回联系人摘要信息（如姓名、ID、是否有号码等），并不包含电话号码本身。电话号码实际存储在独立的 Phone 子表（ContactsContract.CommonDataKinds.Phone）中，必须通过关联查询或二次查询获取。
✅ 正确流程：两步查询法（推荐）
第一步：通过 contactUri 获取联系人 ID 和 HAS_PHONE_NUMBER
确保你传入的是一个有效的 content://com.android.contacts/contacts/xxx 类型 URI（例如从 Intent.ACTION_PICK 或 ActivityResultLauncher 返回）。先查询主联系人表确认该联系人是否含号码：
// 1. 查询 Contacts 表，获取 contactId 和 hasPhoneNumber 标志
String[] contactProjection = {
ContactsContract.Contacts._ID,
ContactsContract.Contacts.HAS_PHONE_NUMBER,
ContactsContract.Contacts.DISPLAY_NAME
};
Cursor contactCursor = getContentResolver().query(
contactUri, contactProjection, null, null, null
);
if (contactCursor != null && contactCursor.moveToFirst()) {
String contactId = contactCursor.getString(
contactCursor.getColumnIndexOrThrow(ContactsContract.Contacts._ID)
);
int hasPhone = contactCursor.getInt(
contactCursor.getColumnIndexOrThrow(ContactsContract.Contacts.HAS_PHONE_NUMBER)
);
String name = contactCursor.getString(
contactCursor.getColumnIndexOrThrow(ContactsContract.Contacts.DISPLAY_NAME)
);
if (hasPhone > 0) {
// 继续查询 Phone 子表
retrievePhoneNumberByContactId(contactId, name);
} else {
Log.w("Contact", "Contact has no phone number");
}
}
contactCursor?.close();
第二步：使用 contactId 查询 Phone 子表获取号码
构建针对 Phone.CONTENT_URI 的查询，通过 CONTACT_ID = ? 关联：
private void retrievePhoneNumberByContactId(String contactId, String name) {
String[] phoneProjection = {
ContactsContract.CommonDataKinds.Phone.NUMBER,
ContactsContract.CommonDataKinds.Phone.TYPE,
ContactsContract.CommonDataKinds.Phone.LABEL
};
// ✅ 关键：查询 Phone 表，而非 Contacts 表
Uri phoneUri = ContactsContract.CommonDataKinds.Phone.CONTENT_URI;
String selection = ContactsContract.CommonDataKinds.Phone.CONTACT_ID + " = ?";
try (Cursor phoneCursor = getContentResolver().query(
phoneUri,
phoneProjection,
selection,
new String[]{contactId},
null)) {
if (phoneCursor != null && phoneCursor.moveToFirst()) {
do {
String number = phoneCursor.getString(
phoneCursor.getColumnIndexOrThrow(ContactsContract.CommonDataKinds.Phone.NUMBER)
);
int type = phoneCursor.getInt(
phoneCursor.getColumnIndexOrThrow(ContactsContract.CommonDataKinds.Phone.TYPE)
);
String label = phoneCursor.getString(
phoneCursor.getColumnIndexOrThrow(ContactsContract.CommonDataKinds.Phone.LABEL)
);
Log.d("ContactPhone", String.format("Name: %s | Number: %s | Type: %d | Label: %s",
name, number, type, label == null ? "N/A" : label));
// ✅ 成功获取到号码，可封装返回
ContactInfo info = new ContactInfo(name, number.trim());
// ... 处理 info
break; // 取第一个号码；如需全部，移除此 break 并循环
} while (phoneCursor.moveToNext());
} else {
Log.w("ContactPhone", "No phone number found for contact ID: " + contactId);
}
}
}
⚠️ 关键注意事项
-
权限声明（Android 6.0+ 必须动态申请）：
除<uses-permission android:name="android.permission.READ_CONTACTS"></uses-permission>外，部分 OEM（如 Samsung、Xiaomi、华为）要求额外声明READ_CALL_LOG（即使你不读通话记录），否则Phone.NUMBER列将为空或查询失败。虽然 Google 官方文档未强制要求，但实测在 Android 10–13 多数设备上为必要项：<uses-permission android:name="android.permission.READ_CALL_LOG"></uses-permission>
? 动态申请时，只需请求
READ_CONTACTS（READ_CALL_LOG在 targetSdkVersion ≥ 33 后已废弃且不可单独申请），但Manifest 中仍建议同时声明两者以兼容旧设备。 不要硬编码
DISPLAY_NAME_PRIMARY：
你代码中使用了ContactsContract.CommonDataKinds.Phone.DISPLAY_NAME_PRIMARY，但此字段属于Phone表的冗余列，强烈建议改用主表的DISPLAY_NAME（更稳定），或直接通过contactId关联获取。避免
getColumnIndex(...)返回 -1 的陷阱：
永远使用getColumnIndexOrThrow()替代getColumnIndex()，并在try-catch中捕获IllegalArgumentException，便于快速定位字段名拼写或表结构错误。contactUri来源必须正确：
若从Intent.ACTION_PICK获取，确保 Intent 的setData()指向ContactsContract.Contacts.CONTENT_URI（而非Phone.CONTENT_URI）。错误的 URI 是导致列缺失的最常见原因。
✅ 总结
获取联系人电话号码不是单次查询就能完成的任务，而是典型的「主–从表关联查询」场景。核心原则是：
? Contacts 表 → 查 ID 和是否有号码标志；
? Phone 表 → 用 contactId 查具体号码。
跳过第一步直接查 Phone 表（或误用 Contacts 表 URI）必然失败；忽略 OEM 权限差异则会导致兼容性问题。按本文流程实现，即可在所有主流 Android 设备上稳定获取联系人手机号。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
