• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Contacts Kit开发概述
2
3<!--Kit: Contacts Kit-->
4<!--Subsystem: Applications-->
5<!--Owner: @librahCode-->
6<!--Designer: @yanghaoqian-->
7<!--Tester: @shangzhijie-->
8<!--Adviser: @zhang_yixin13-->
9Contacts Kit可以帮助开发者轻松实现联系人的增删改查等功能。该Kit提供了一系列API，可以让开发者在应用中快速集成联系人管理功能。
10
11详情请参考[@ohos.contact API](../reference/apis-contacts-kit/js-apis-contact.md)。
12
13
14## 能力范围
15
16通过Contacts Kit，开发者可以对联系人进行管理，包括增加、删除、修改、查询联系人信息。开发者还可以通过Picker的方式，拉起联系人列表。
17
18面向所有应用开放如下能力：
19
20- [使用Picker选择联系人](#使用picker选择联系人)
21
22面向三方应用受限开放如下能力：
23
24<!--RP1-->
25> **注意：**
26>
27> 读取联系人需要声明接口调用的权限：ohos.permission.READ_CONTACTS，此权限级别为system_basic。添加联系人、删除联系人、更新联系人需要声明接口调用的权限：ohos.permission.WRITE_CONTACTS，此权限级别为system_basic。
28<!--RP1End-->
29
30- [联系人管理](#联系人管理受限开放)
31
32
33## 使用Picker选择联系人
34
35当用户选择联系人的时候，通过Picker的方式，拉起联系人列表，引导用户完成界面操作，接口本身无需申请权限。
36
371. 导入相关的联系人模块。
38
39   ```ts
40   import { contact } from '@kit.ContactsKit';
41   import { BusinessError } from '@kit.BasicServicesKit';
42   ```
43
442. 调用联系人接口，拉起联系人列表，用户点击对应的联系人后返回。
45
46   ```ts
47   contact.selectContacts({
48     isMultiSelect:false
49   },(err: BusinessError, data) => {
50       if (err) {
51         console.error('selectContact callback, errCode:' + err.code + ', errMessage:' + err.message);
52           return;
53       }
54       console.info(`selectContact callback: success data->${JSON.stringify(data)}`);
55   });
56
57   ```
58
593. 完成操作，返回想要的data数据。
60
61
62## 联系人管理（受限开放）
63
64若需要在应用内实现管理联系人的功能，可以使用permissions接口获取应用对联系人的编辑权限。
65
661. 声明接口调用所需要的权限。
67   <!--RP2-->
68   - 删除联系人，调用deleteContact接口，需要配置ohos.permission.WRITE_CONTACTS权限，权限级别为system_basic。
69   - 更新联系人，调用updateContact接口，需要配置ohos.permission.WRITE_CONTACTS权限，权限级别为system_basic。
70   - 查询联系人，调用queryContact接口，需要配置ohos.permission.READ_CONTACTS权限，权限级别为system_basic。
71   在申请权限前，请保证符合[权限使用的基本原则](../security/AccessToken/app-permission-mgmt-overview.md#权限使用的基本原则)。然后参考[申请应用权限](../security/AccessToken/determine-application-mode.md#system_basic等级应用申请权限的方式)声明对应权限。
72   <!--RP2End-->
73
742. 设置一个需要的Permissions数组变量。
75
763. 执行对应联系人的权限操作。
77
78  ```ts
79  // 示例代码
80  import { common, abilityAccessCtrl, Permissions, PermissionRequestResult } from '@kit.AbilityKit';
81  import { contact } from '@kit.ContactsKit';
82  import { BusinessError } from '@kit.BasicServicesKit';
83
84  @Entry
85  @Component
86  struct Contact {
87    addContactByPermissions() {
88      // 在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext
89      let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
90      const permissions: Array<Permissions> = ['ohos.permission.WRITE_CONTACTS'];
91      const contactInfo: contact.Contact = {
92        name: { fullName: '王小明' },
93        phoneNumbers: [{ phoneNumber: '13912345678' }]
94      }
95      abilityAccessCtrl.createAtManager().requestPermissionsFromUser(context, permissions).then((result: PermissionRequestResult) => {
96        if (result.authResults[0] !== 0) { // 0 表示请求权限成功，其他任何非零值表示请求失败
97          console.error('request contact permissions failed');
98          return;
99        }
100        contact.addContact(context, contactInfo).then((data) => {
101          console.info(`Succeeded in adding Contact. data: ${JSON.stringify(data)}`);
102        }).catch((err: BusinessError) => {
103          console.error(`Failed to add Contact. Code: ${err.code}, message: ${err.message}`);
104        });
105      })
106    }
107
108    build() {
109      Row() {
110        Column() {
111          Button('添加联系人')
112            .onClick(() => {
113              this.addContactByPermissions();
114            })
115        }
116        .width('100%')
117      }
118      .height('100%')
119    }
120  }
121```
122