Scripting
文档
更新日志
隐私
文档
更新日志
隐私
简体中文

通讯录

Scripting 提供 Contact 模块，允许在脚本中访问和管理设备上的联系人数据，包括创建、查询、更新、删除联系人，以及操作联系人组和容器。

基本概念

类型 描述
ContactInfo 表示单个联系人的完整信息。
ContactContainer 联系人存储容器，来源如本地、Exchange、CardDAV 等。
ContactGroup 联系人组，用于将联系人分类管理。
ContactLabeledValue 带标签的值，如电话、邮箱。
ContactPostalAddress 邮寄地址信息。
ContactSocialProfile 社交账号信息。
ContactInstantMessageAddress 即时通讯信息。

创建联系人

1try {
2  const contact = await Contact.createContact({
3    givenName: 'John',
4    familyName: 'Doe',
5    phoneNumbers: [{ label: 'mobile', value: '+1234567890' }],
6    emailAddresses: [{ label: 'work', value: 'john.doe@example.com' }]
7  })
8  console.log('联系人创建成功:', contact)
9} catch (error) {
10  console.error('创建联系人失败:', error)
11}

说明：

  • givenName 或 familyName 至少填写一项
  • 可指定 containerIdentifier，否则加入默认容器
  • 建议捕获异常，避免因权限或参数问题导致脚本崩溃

更新联系人

1try {
2  const updated = await Contact.updateContact({
3    identifier: contact.identifier,
4    phoneNumbers: [{ label: 'home', value: '+9876543210' }]
5  })
6  console.log('联系人更新成功:', updated)
7} catch (error) {
8  console.error('更新联系人失败:', error)
9}

更新说明：

  • 必须传入 identifier
  • 仅修改提供的字段，其他信息不变

查询联系人

通过唯一标识符查询

1try {
2  const contact = await Contact.fetchContact(contactId, { fetchImageData: true })
3  console.log('联系人信息:', contact)
4} catch (error) {
5  console.error('查询联系人失败:', error)
6}

查询所有联系人

1try {
2  const contacts = await Contact.fetchAllContacts({ fetchImageData: false })
3  console.log('联系人列表:', contacts)
4} catch (error) {
5  console.error('获取联系人列表失败:', error)
6}

查询指定容器或组内的联系人

1try {
2  const contacts = await Contact.fetchContactsInContainer(containerId)
3  console.log('容器内联系人:', contacts)
4} catch (error) {
5  console.error('查询容器内联系人失败:', error)
6}
7
8try {
9  const groupContacts = await Contact.fetchContactsInGroup(groupId)
10  console.log('组内联系人:', groupContacts)
11} catch (error) {
12  console.error('查询组内联系人失败:', error)
13}

删除联系人

1try {
2  await Contact.deleteContact(contactId)
3  console.log('联系人已删除')
4} catch (error) {
5  console.error('删除联系人失败:', error)
6}

容器管理

获取所有容器

1try {
2  const containers = await Contact.fetchContainers()
3  console.log('联系人容器:', containers)
4} catch (error) {
5  console.error('获取容器失败:', error)
6}

获取默认容器

1try {
2  const defaultContainerId = await Contact.defaultContainerIdentifier
3  console.log('默认容器ID:', defaultContainerId)
4} catch (error) {
5  console.error('获取默认容器失败:', error)
6}

联系人组管理

创建联系人组

1try {
2  const group = await Contact.createGroup('Friends', defaultContainerId)
3  console.log('联系人组创建成功:', group)
4} catch (error) {
5  console.error('创建联系人组失败:', error)
6}

获取联系人组

1try {
2  const groups = await Contact.fetchGroups()
3  console.log('联系人组列表:', groups)
4} catch (error) {
5  console.error('获取联系人组失败:', error)
6}

删除联系人组

1try {
2  await Contact.deleteGroup(groupId)
3  console.log('联系人组已删除')
4} catch (error) {
5  console.error('删除联系人组失败:', error)
6}

联系人与组的关系管理

添加联系人到指定组

1try {
2  await Contact.addContactToGroup(contactId, groupId)
3  console.log('联系人已添加到组')
4} catch (error) {
5  console.error('添加联系人到组失败:', error)
6}

从组中移除联系人

1try {
2  await Contact.removeContactFromGroup(contactId, groupId)
3  console.log('联系人已从组中移除')
4} catch (error) {
5  console.error('从组中移除联系人失败:', error)
6}

ContactInfo 数据结构示例

1{
2  "identifier": "XXXX-XXXX",
3  "givenName": "John",
4  "familyName": "Doe",
5  "phoneNumbers": [{ "label": "mobile", "value": "+1234567890" }],
6  "emailAddresses": [{ "label": "work", "value": "john@example.com" }],
7  "postalAddresses": [{
8    "label": "home",
9    "street": "123 Apple St.",
10    "city": "Cupertino",
11    "state": "CA",
12    "postalCode": "95014",
13    "country": "USA",
14    "isoCountryCode": "US"
15  }]
16}

注意事项

  • 所有 API 操作都可能因权限、数据错误等原因失败，建议统一加上 try-catch
  • 访问联系人前，请确保获取用户授权
  • imageData 建议按需加载，避免性能问题
  • 更新和删除操作必须确保 identifier 正确有效

完整示例：创建并查询联系人

1try {
2  const contact = await Contact.createContact({
3    givenName: 'Alice',
4    familyName: 'Smith',
5    phoneNumbers: [{ label: 'mobile', value: '+19876543210' }]
6  })
7  console.log('联系人创建成功:', contact)
8
9  const fetched = await Contact.fetchContact(contact.identifier)
10  console.log('查询到联系人:', fetched.givenName)
11} catch (error) {
12  console.error('操作失败:', error)
13}
大纲