js-apis-contact.md 75.5 KB
Newer Older
O
ohos-lsw 已提交
1 2
# 联系人

T
explain  
tianyu 已提交
3 4
本模块提供联系人管理能力,包括添加联系人、删除联系人、更新联系人等

O
ohos-lsw 已提交
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
>**说明:**
>
>本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。


## 导入模块

```
import contact from '@ohos.contact';
```

## contact.addContact

addContact(contact:Contact, callback:AsyncCallback<number>): void

添加联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.WRITE_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
27 28 29 30
| 参数名   | 类型                        | 必填 | 说明                           |
| -------- | --------------------------- | ---- | ------------------------------ |
| contact  | [Contact](#contact)         | 是   | 联系人信息。                   |
| callback | AsyncCallback<number> | 是   | 回调函数,返回添加的联系人id。 |
O
ohos-lsw 已提交
31 32 33

**示例:**

Z
zengyawen 已提交
34
  ```js
O
ohos-lsw 已提交
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
  contact.addContact({
      fullName: {fullName: 'xxx'},
      phoneNumbers: [{phoneNumber: '138xxxxxxxx'}]
  }, (err, data) => {
      if (err) {
          console.log(`addContact callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`addContact callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.addContact

addContact(contact: Contact): Promise<number>

添加联系人,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.WRITE_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
59 60 61
| 参数名  | 类型                | 必填 | 说明         |
| ------- | ------------------- | ---- | ------------ |
| contact | [Contact](#contact) | 是   | 联系人信息。 |
O
ohos-lsw 已提交
62 63

**返回值:**
H
update  
HelloCrease 已提交
64 65
| 类型                  | 说明                                        |
| --------------------- | ------------------------------------------- |
O
ohos-lsw 已提交
66 67 68 69
| Promise<number> | 以Promise形式返回结果,返回添加的联系人id。 |

**示例:**

Z
zengyawen 已提交
70
  ```js
O
ohos-lsw 已提交
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
  let promise = contact.addContact({
      name: {fullName: 'xxx'},
      phoneNumbers: [{phoneNumber: '138xxxxxxxx'}]
  });
  promise.then((data) => {
      console.log(`addContact success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`addContact fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.deleteContact

deleteContact(key: string, callback: AsyncCallback<void>): void

删除联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.WRITE_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
94 95 96 97
| 参数名   | 类型                      | 必填 | 说明                                 |
| -------- | ------------------------- | ---- | ------------------------------------ |
| key      | string                    | 是   | 联系人key值,一个联系人对应一个key。 |
| callback | AsyncCallback<void> | 是   | 回调函数,返回删除联系人的结果。     |
O
ohos-lsw 已提交
98 99 100

**示例:**

Z
zengyawen 已提交
101
  ```js
O
ohos-lsw 已提交
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
  contact.deleteContact('xxx', (err) => {
      if (err) {
          console.log(`deleteContact callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log('deleteContact success');
  });
  ```


## contact.deleteContact

deleteContact(key: string): Promise<void>

删除联系人,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.WRITE_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
123 124 125
| 参数名 | 类型   | 必填 | 说明                                   |
| ------ | ------ | ---- | -------------------------------------- |
| key    | string | 是   | 联系人的key值,一个联系人对应一个key。 |
O
ohos-lsw 已提交
126 127

**返回值:**
H
update  
HelloCrease 已提交
128 129
| 类型                | 说明                                          |
| ------------------- | --------------------------------------------- |
O
ohos-lsw 已提交
130 131 132 133
| Promise<void> | 以Promise形式返回结果,返回删除联系人的结果。 |

**示例:**

Z
zengyawen 已提交
134
  ```js
O
ohos-lsw 已提交
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
  let promise = contact.deleteContact('xxx');
  promise.then(() => {
      console.log(`deleteContact success`);
  }).catch((err) => {
      console.error(`deleteContact fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.updateContact

updateContact(contact: Contact, callback: AsyncCallback<void>): void

更新联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.WRITE_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
155 156 157 158
| 参数名   | 类型                      | 必填 | 说明                                 |
| -------- | ------------------------- | ---- | ------------------------------------ |
| contact  | [Contact](#contact)       | 是   | 联系人信息。                         |
| callback | AsyncCallback<void> | 是   | 回调函数,返回更新联系人的更新结果。 |
O
ohos-lsw 已提交
159 160 161

**示例:**

Z
zengyawen 已提交
162
  ```js
O
ohos-lsw 已提交
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
  contact.updateContact({
      name: {fullName: 'xxx'},
      phoneNumbers: [{phoneNumber: '138xxxxxxxx'}]
  }, (err) => {
      if (err) {
          console.log('updateContact callback: err->${JSON.stringify(err)}');
          return;
      }
      console.log('updateContact success');
  });
  ```


## contact.updateContact

updateContact(contact: Contact, attrs: ContactAttributes, callback: AsyncCallback<void>): void

更新联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.WRITE_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
187 188 189 190 191
| 参数名   | 类型                                    | 必填 | 说明                                 |
| -------- | --------------------------------------- | ---- | ------------------------------------ |
| contact  | [Contact](#contact)                     | 是   | 联系人信息。                         |
| attrs    | [ContactAttributes](#contactattributes) | 是   | 联系人的属性列表。                   |
| callback | AsyncCallback<void>               | 是   | 回调函数,返回更新联系人的更新结果。 |
O
ohos-lsw 已提交
192 193 194

**示例:**

Z
zengyawen 已提交
195
  ```js
O
ohos-lsw 已提交
196 197 198 199
  contact.updateContact({
      fullName: {fullName: 'xxx'},
      phoneNumbers: [{phoneNumber: '138xxxxxxxx'}]
  },{
Q
qian-nan-xu 已提交
200
      attributes:[contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
  }, (err) => {
      if (err) {
          console.log('updateContact callback: err->${JSON.stringify(err)}');
          return;
      }
      console.log('updateContact success');
  });
  ```


## contact.updateContact

updateContact(contact: Contact, attrs?: ContactAttributes): Promise<void>

更新联系人,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.WRITE_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
222 223 224 225
| 参数名  | 类型                                    | 必填 | 说明               |
| ------- | --------------------------------------- | ---- | ------------------ |
| contact | [Contact](#contact)                     | 是   | 联系人信息。       |
| attrs   | [ContactAttributes](#contactattributes) | 否   | 联系人的属性列表。 |
O
ohos-lsw 已提交
226 227

**返回值:**
H
update  
HelloCrease 已提交
228 229
| 类型                | 说明                                              |
| ------------------- | ------------------------------------------------- |
O
ohos-lsw 已提交
230 231 232 233
| Promise<void> | 以Promise形式返回结果,返回更新联系人的更新结果。 |

**示例:**

Z
zengyawen 已提交
234
  ```js
O
ohos-lsw 已提交
235 236 237 238
  let promise = contact.updateContact({
      fullName: {fullName: 'xxx'},
      phoneNumbers: [{phoneNumber: '138xxxxxxxx'}]
  }, {
Q
qian-nan-xu 已提交
239
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259
  });
  promise.then(() => {
      console.log('updateContact success');
  }).catch((err) => {
      console.error(`updateContact fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.isLocalContact

isLocalContact(id: number, callback: AsyncCallback<boolean>): void

判断当前联系人id是否在电话簿中,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
260 261 262 263
| 参数名   | 类型                         | 必填 | 说明                                                         |
| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
| id       | number                       | 是   | 联系人对象的id属性,一个联系人对应一个id。                   |
| callback | AsyncCallback<boolean> | 是   | 回调函数,返回布尔值。true代表联系人id在本地电话簿中,false则代表联系人id不在本地电话簿中。 |
O
ohos-lsw 已提交
264 265 266

**示例:**

Z
zengyawen 已提交
267
  ```js
O
ohos-lsw 已提交
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
  contact.isLocalContact(/*id*/1, (err, data) => {
      if (err) {
          console.log(`isLocalContact callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`isLocalContact callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.isLocalContact

isLocalContact(id: number): Promise<boolean>

判断当前联系人id是否在电话簿中,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
289 290 291
| 参数名 | 类型   | 必填 | 说明                                       |
| ------ | ------ | ---- | ------------------------------------------ |
| id     | number | 是   | 联系人对象的id属性,一个联系人对应一个id。 |
O
ohos-lsw 已提交
292 293

**返回值:**
H
update  
HelloCrease 已提交
294 295
| 类型                   | 说明                                                         |
| ---------------------- | ------------------------------------------------------------ |
O
ohos-lsw 已提交
296 297 298 299
| Promise<boolean> | 以Promise形式返回结果,返回布尔值。true代表联系人id在本地电话簿中,false则代表联系人id不在本地电话簿中。 |

**示例:**

Z
zengyawen 已提交
300
  ```js
O
ohos-lsw 已提交
301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320
  let promise = contact.isLocalContact(/*id*/1);
  promise.then((data) => {
      console.log(`isLocalContact success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`isLocalContact fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.isMyCard

isMyCard(id: number, callback: AsyncCallback<boolean>): void

判断是否为“我的名片”,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
321 322 323 324
| 参数名   | 类型                         | 必填 | 说明                                                         |
| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
| id       | number                       | 是   | 联系人对象的id属性。                                         |
| callback | AsyncCallback<boolean> | 是   | 回调函数,返回是否为“我的名片”的布尔值。true代表此联系人是“我的名片”,false则代表不是。 |
O
ohos-lsw 已提交
325 326 327

**示例:**

Z
zengyawen 已提交
328
  ```js
O
ohos-lsw 已提交
329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349
  contact.isMyCard(/*id*/1, (err, data) => {
      if (err) {
          console.log(`isMyCard callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`isMyCard callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.isMyCard

isMyCard(id: number): Promise<boolean>

判断是否为“我的名片”,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
350 351 352
| 参数名 | 类型   | 必填 | 说明                 |
| ------ | ------ | ---- | -------------------- |
| id     | number | 是   | 联系人对象的id属性。 |
O
ohos-lsw 已提交
353 354

**返回值:**
H
update  
HelloCrease 已提交
355 356
| 类型                   | 说明                                                         |
| ---------------------- | ------------------------------------------------------------ |
O
ohos-lsw 已提交
357 358 359 360
| Promise<boolean> | 以Promise形式返回结果,返回是否为“我的名片”的布尔值。true代表此联系人是“我的名片”,false则代表不是。 |

**示例:**

Z
zengyawen 已提交
361
  ```js
O
ohos-lsw 已提交
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381
  let promise = contact.isMyCard(/*id*/1);
  promise.then((data) => {
      console.log(`isMyCard success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`isMyCard fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.queryMyCard

queryMyCard(callback: AsyncCallback<Contact>): void

查询“我的名片”,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
382 383 384
| 参数名   | 类型                                     | 必填 | 说明                           |
| -------- | ---------------------------------------- | ---- | ------------------------------ |
| callback | AsyncCallback<[Contact](#contact)> | 是   | 回调函数,返回“我的名片”信息。 |
O
ohos-lsw 已提交
385 386 387

**示例:**

Z
zengyawen 已提交
388
  ```js
O
ohos-lsw 已提交
389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409
  contact.queryMyCard((err, data) => {
      if (err) {
          console.log(`queryMyCard callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryMyCard callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryMyCard

queryMyCard(attrs: ContactAttributes, callback: AsyncCallback<Contact>): void

查询“我的名片”,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
410 411 412 413
| 参数名   | 类型                                     | 必填 | 说明                           |
| -------- | ---------------------------------------- | ---- | ------------------------------ |
| attrs    | [ContactAttributes](#contactattributes)  | 是   | 联系人的属性列表。             |
| callback | AsyncCallback<[Contact](#contact)> | 是   | 回调函数,返回“我的名片”信息。 |
O
ohos-lsw 已提交
414 415 416

**示例:**

Z
zengyawen 已提交
417
  ```js
O
ohos-lsw 已提交
418
  contact.queryMyCard({
Q
qian-nan-xu 已提交
419
      attributes:[contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440
  }, (err, data) => {
      if (err) {
          console.log(`queryMyCard callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryMyCard callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryMyCard

queryMyCard(attrs?: ContactAttributes): Promise<Contact>

查询“我的名片”,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
441 442 443
| 参数名 | 类型                                    | 必填 | 说明               |
| ------ | --------------------------------------- | ---- | ------------------ |
| attrs  | [ContactAttributes](#contactattributes) | 否   | 联系人的属性列表。 |
O
ohos-lsw 已提交
444 445

**返回值:**
H
update  
HelloCrease 已提交
446 447
| 类型                               | 说明                                        |
| ---------------------------------- | ------------------------------------------- |
O
ohos-lsw 已提交
448 449 450 451
| Promise<[Contact](#contact)> | 以Promise形式返回结果,返回“我的名片”信息。 |

**示例:**

Z
zengyawen 已提交
452
  ```js
O
ohos-lsw 已提交
453
  let promise = contact.queryMyCard({
Q
qian-nan-xu 已提交
454
      attributes:[contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
455 456 457 458 459 460 461 462 463
  });
  promise.then((data) => {
      console.log(`queryMyCard success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`queryMyCard fail: err->${JSON.stringify(err)}`);
  });
  ```


H
update  
HelloCrease 已提交
464
## contact.selectContact
O
ohos-lsw 已提交
465

Z
zengyawen 已提交
466
selectContact(callback: AsyncCallback<Array<Contact>>): void
O
ohos-lsw 已提交
467 468 469 470 471 472 473 474

选择联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.Contacts、SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
475 476 477
| 参数名   | 类型                                                  | 必填 | 说明                                 |
| -------- | ----------------------------------------------------- | ---- | ------------------------------------ |
| callback | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回选择的联系人对象数组。 |
O
ohos-lsw 已提交
478 479 480

**示例:**

Z
zengyawen 已提交
481
  ```js
O
ohos-lsw 已提交
482 483 484 485 486 487 488 489 490 491
  contact.selectContact((err, data) => {
      if (err) {
          console.log(`selectContact callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`selectContact callback: success data->${JSON.stringify(data)}`);
  });
  ```


H
update  
HelloCrease 已提交
492
## contact.selectContact
O
ohos-lsw 已提交
493 494 495 496 497 498 499 500 501 502

selectContact(): Promise<Array<Contact>>

选择联系人,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.Contacts、SystemCapability.Applications.ContactsData

**返回值:**
H
update  
HelloCrease 已提交
503 504
| 类型                                            | 说明                                              |
| ----------------------------------------------- | ------------------------------------------------- |
O
ohos-lsw 已提交
505 506 507 508
| Promise<Array<[Contact](#contact)>> | 以Promise形式返回结果,返回选择的联系人对象数组。 |

**示例:**

Z
zengyawen 已提交
509
  ```js
O
ohos-lsw 已提交
510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529
  let promise = contact.selectContact();
  promise.then((data) => {
      console.log(`selectContact success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`selectContact fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.queryContact

queryContact(key: string,  callback: AsyncCallback<Contact>): void

根据key查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
530 531 532 533
| 参数名   | 类型                                     | 必填 | 说明                                   |
| -------- | ---------------------------------------- | ---- | -------------------------------------- |
| key      | string                                   | 是   | 联系人的key值,一个联系人对应一个key。 |
| callback | AsyncCallback<[Contact](#contact)> | 是   | 回调函数,返回查询的联系人对象。       |
O
ohos-lsw 已提交
534 535 536

**示例:**

Z
zengyawen 已提交
537
  ```js
O
ohos-lsw 已提交
538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558
  contact.queryContact('xxx', (err, data) => {
      if (err) {
          console.log(`queryContact callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContact callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContact

queryContact(key: string, holder: Holder, callback: AsyncCallback<Contact>): void

根据key查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
559 560 561 562 563
| 参数名   | 类型                                     | 必填 | 说明                                   |
| -------- | ---------------------------------------- | ---- | -------------------------------------- |
| key      | string                                   | 是   | 联系人的key值,一个联系人对应一个key。 |
| holder   | [Holder](#holder)                        | 是   | 创建联系人的应用信息。                 |
| callback | AsyncCallback<[Contact](#contact)> | 是   | 回调函数,返回查询的联系人对象。       |
O
ohos-lsw 已提交
564 565 566

**示例:**

Z
zengyawen 已提交
567
  ```js
O
ohos-lsw 已提交
568
  contact.queryContact('xxx', {
Q
qian-nan-xu 已提交
569 570 571
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592
  }, (err, data) => {
      if (err) {
          console.log(`queryContact callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContact callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContact

queryContact(key: string,  attrs: ContactAttributes, callback: AsyncCallback<Contact>): void

根据key查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
593 594 595 596 597
| 参数名   | 类型                                     | 必填 | 说明                                   |
| -------- | ---------------------------------------- | ---- | -------------------------------------- |
| key      | string                                   | 是   | 联系人的key值,一个联系人对应一个key。 |
| attrs    | [ContactAttributes](#contactattributes)  | 是   | 联系人的属性列表。                     |
| callback | AsyncCallback<[Contact](#contact)> | 是   | 回调函数,返回查询的联系人对象。       |
O
ohos-lsw 已提交
598 599 600

**示例:**

Z
zengyawen 已提交
601
  ```js
O
ohos-lsw 已提交
602
  contact.queryContact('xxx', {
Q
qian-nan-xu 已提交
603
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624
  }, (err, data) => {
      if (err) {
          console.log(`queryContact callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContact callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContact

queryContact(key: string, holder: Holder, attrs: ContactAttributes, callback: AsyncCallback<Contact>): void

根据key查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
625 626 627 628 629 630
| 参数名   | 类型                                     | 必填 | 说明                                   |
| -------- | ---------------------------------------- | ---- | -------------------------------------- |
| key      | string                                   | 是   | 联系人的key值,一个联系人对应一个key。 |
| holder   | [Holder](#holder)                        | 是   | 创建联系人的应用信息。                 |
| attrs    | [ContactAttributes](#contactattributes)  | 是   | 联系人的属性列表。                     |
| callback | AsyncCallback<[Contact](#contact)> | 是   | 回调函数,返回查询的联系人对象。       |
O
ohos-lsw 已提交
631 632 633

**示例:**

Z
zengyawen 已提交
634
  ```js
O
ohos-lsw 已提交
635
  contact.queryContact('xxx', {
Q
qian-nan-xu 已提交
636 637 638
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
639
  }, {
Q
qian-nan-xu 已提交
640
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661
  }, (err, data) => {
      if (err) {
          console.log(`queryContact callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContact callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContact

queryContact(key: string, holder?: Holder, attrs?: ContactAttributes): Promise<Contact>

根据key查询联系人,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
662 663 664 665 666
| 参数名 | 类型                                    | 必填 | 说明                                   |
| ------ | --------------------------------------- | ---- | -------------------------------------- |
| key    | string                                  | 是   | 联系人的key值,一个联系人对应一个key。 |
| holder | [Holder](#holder)                       | 否   | 创建联系人的应用信息。                 |
| attrs  | [ContactAttributes](#contactattributes) | 否   | 联系人的属性列表。                     |
O
ohos-lsw 已提交
667 668

**返回值:**
H
update  
HelloCrease 已提交
669 670
| 类型                               | 说明                                            |
| ---------------------------------- | ----------------------------------------------- |
O
ohos-lsw 已提交
671 672 673 674
| Promise<[Contact](#contact)> | 以Promise形式返回结果,返回查询到的联系人对象。 |

**示例:**

Z
zengyawen 已提交
675
  ```js
O
ohos-lsw 已提交
676
  let promise = contact.queryContact('xxx', {
Q
qian-nan-xu 已提交
677 678 679
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
680
  }, {
Q
qian-nan-xu 已提交
681
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701
  });
  promise.then((data) => {
      console.log(`queryContact success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`queryContact fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.queryContacts

queryContacts(callback: AsyncCallback<Array<Contact>>): void

查询所有联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
702 703 704
| 参数名   | 类型                                                  | 必填 | 说明                                   |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| callback | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到的联系人对象数组。 |
O
ohos-lsw 已提交
705 706 707

**示例:**

Z
zengyawen 已提交
708
  ```js
O
ohos-lsw 已提交
709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729
  contact.queryContacts((err, data) => {
      if (err) {
          console.log(`queryContacts callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContacts callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContacts

queryContacts(holder: Holder, callback: AsyncCallback<Array<Contact>>): void

查询所有联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
730 731 732 733
| 参数名   | 类型                                                  | 必填 | 说明                                   |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| holder   | [Holder](#holder)                                     | 是   | 创建联系人的应用信息。                 |
| callback | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到的联系人对象数组。 |
O
ohos-lsw 已提交
734 735 736

**示例:**

Z
zengyawen 已提交
737
  ```js
O
ohos-lsw 已提交
738
  contact.queryContacts({
Q
qian-nan-xu 已提交
739 740 741
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762
  }, (err, data) => {
      if (err) {
          console.log(`queryContacts callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContacts callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContacts

queryContacts(attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void

查询所有联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
763 764 765 766
| 参数名   | 类型                                                  | 必填 | 说明                                   |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| attrs    | [ContactAttributes](#contactattributes)               | 是   | 联系人的属性列表。                     |
| callback | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到的联系人对象数组。 |
O
ohos-lsw 已提交
767 768 769

**示例:**

Z
zengyawen 已提交
770
  ```js
O
ohos-lsw 已提交
771
  contact.queryContacts({
Q
qian-nan-xu 已提交
772
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
773 774 775 776 777 778 779 780 781 782 783 784
  }, (err, data) => {
      if (err) {
          console.log(`queryContacts callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContacts callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContacts

C
clevercong 已提交
785
queryContacts(holder: Holder, attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void
O
ohos-lsw 已提交
786 787 788 789 790 791 792 793

查询所有联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
794 795 796 797 798
| 参数名   | 类型                                                  | 必填 | 说明                                   |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| holder   | [Holder](#holder)                                     | 是   | 创建联系人的应用信息。                 |
| attrs    | [ContactAttributes](#contactattributes)               | 是   | 联系人的属性列表。                     |
| callback | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到的联系人对象数组。 |
O
ohos-lsw 已提交
799 800 801

**示例:**

Z
zengyawen 已提交
802
  ```js
O
ohos-lsw 已提交
803
  contact.queryContacts({
Q
qian-nan-xu 已提交
804 805 806
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
807
  }, {
Q
qian-nan-xu 已提交
808
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829
  }, (err, data) => {
      if (err) {
          console.log(`queryContacts callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContacts callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContacts

queryContacts(holder?: Holder, attrs?: ContactAttributes): Promise<Array<Contact>>

查询所有联系人,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
830 831 832 833
| 参数名 | 类型                                    | 必填 | 说明                   |
| ------ | --------------------------------------- | ---- | ---------------------- |
| holder | [Holder](#holder)                       | 否   | 创建联系人的应用信息。 |
| attrs  | [ContactAttributes](#contactattributes) | 否   | 联系人的属性列表。     |
O
ohos-lsw 已提交
834 835

**返回值:**
H
update  
HelloCrease 已提交
836 837
| 类型                                            | 说明                                                |
| ----------------------------------------------- | --------------------------------------------------- |
O
ohos-lsw 已提交
838 839 840 841
| Promise<Array<[Contact](#contact)>> | 以Promise形式返回结果,返回查询到的联系人对象数组。 |

**示例:**

Z
zengyawen 已提交
842
  ```js
O
ohos-lsw 已提交
843
  let promise = contact.queryContacts({
Q
qian-nan-xu 已提交
844 845 846
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
847
  }, {
Q
qian-nan-xu 已提交
848
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868
  });
  promise.then((data) => {
      console.log(`queryContacts success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`queryContacts fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.queryContactsByPhoneNumber

queryContactsByPhoneNumber(phoneNumber: string, callback: AsyncCallback<Array<Contact>>): void

根据电话号码查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
869 870 871 872
| 参数名      | 类型                                                  | 必填 | 说明                                   |
| ----------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| phoneNumber | string                                                | 是   | 联系人的电话号码。                     |
| callback    | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到的联系人对象数组。 |
O
ohos-lsw 已提交
873 874 875

**示例:**

Z
zengyawen 已提交
876
  ```js
O
ohos-lsw 已提交
877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897
  contact.queryContactsByPhoneNumber('138xxxxxxxx', (err, data) => {
      if (err) {
          console.log(`queryContactsByPhoneNumber callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContactsByPhoneNumber callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContactsByPhoneNumber

queryContactsByPhoneNumber(phoneNumber: string, holder: Holder, callback: AsyncCallback<Array<Contact>>): void

根据电话号码查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
898 899 900 901 902
| 参数名      | 类型                                                  | 必填 | 说明                                   |
| ----------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| phoneNumber | string                                                | 是   | 联系人的电话号码。                     |
| holder      | [Holder](#holder)                                     | 是   | 创建联系人的应用信息。                 |
| callback    | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到的联系人对象数组。 |
O
ohos-lsw 已提交
903 904 905

**示例:**

Z
zengyawen 已提交
906
  ```js
O
ohos-lsw 已提交
907
  contact.queryContactsByPhoneNumber('138xxxxxxxx', {
Q
qian-nan-xu 已提交
908 909 910
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931
  }, (err, data) => {
      if (err) {
          console.log(`queryContactsByPhoneNumber callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContactsByPhoneNumber callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContactsByPhoneNumber

queryContactsByPhoneNumber(phoneNumber: string, attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void

根据电话号码查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
932 933 934 935 936
| 参数名      | 类型                                                  | 必填 | 说明                                   |
| ----------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| phoneNumber | string                                                | 是   | 联系人的电话号码。                     |
| attrs       | [ContactAttributes](#contactattributes)               | 是   | 联系人的属性列表。                     |
| callback    | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到的联系人对象数组。 |
O
ohos-lsw 已提交
937 938 939

**示例:**

Z
zengyawen 已提交
940
  ```js
O
ohos-lsw 已提交
941
  contact.queryContactsByPhoneNumber('138xxxxxxxx', {
Q
qian-nan-xu 已提交
942
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963
  }, (err, data) => {
      if (err) {
          console.log(`queryContactsByPhoneNumber callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContactsByPhoneNumber callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContactsByPhoneNumber

queryContactsByPhoneNumber(phoneNumber: string, holder: Holder, attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void

根据电话号码查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
964 965 966 967 968 969
| 参数名      | 类型                                                  | 必填 | 说明                                   |
| ----------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| phoneNumber | string                                                | 是   | 联系人的电话号码。                     |
| holder      | [Holder](#holder)                                     | 是   | 创建联系人的应用信息。                 |
| attrs       | [ContactAttributes](#contactattributes)               | 是   | 联系人的属性列表。                     |
| callback    | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到的联系人对象数组。 |
O
ohos-lsw 已提交
970 971 972

**示例:**

Z
zengyawen 已提交
973
  ```js
O
ohos-lsw 已提交
974
  contact.queryContactsByPhoneNumber('138xxxxxxxx', {
Q
qian-nan-xu 已提交
975 976 977
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
978
  }, {
Q
qian-nan-xu 已提交
979
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000
  }, (err, data) => {
      if (err) {
          console.log(`queryContactsByPhoneNumber callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContactsByPhoneNumber callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContactsByPhoneNumber

queryContactsByPhoneNumber(phoneNumber: string, holder?: Holder, attrs?: ContactAttributes): Promise<Array<Contact>>

根据电话号码查询联系人,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1001 1002 1003 1004 1005
| 参数名      | 类型                                    | 必填 | 说明                   |
| ----------- | --------------------------------------- | ---- | ---------------------- |
| phoneNumber | string                                  | 是   | 联系人的电话号码。     |
| holder      | [Holder](#holder)                       | 否   | 创建联系人的应用信息。 |
| attrs       | [ContactAttributes](#contactattributes) | 否   | 联系人的属性列表。     |
O
ohos-lsw 已提交
1006 1007

**返回值:**
H
update  
HelloCrease 已提交
1008 1009
| 类型                                            | 说明                                                |
| ----------------------------------------------- | --------------------------------------------------- |
O
ohos-lsw 已提交
1010 1011 1012 1013
| Promise<Array<[Contact](#contact)>> | 以Promise形式返回结果,返回查询到的联系人对象数组。 |

**示例:**

Z
zengyawen 已提交
1014
  ```js
O
ohos-lsw 已提交
1015
  let promise = contact.queryContactsByPhoneNumber('138xxxxxxxx', {
Q
qian-nan-xu 已提交
1016 1017 1018
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
1019
  }, {
Q
qian-nan-xu 已提交
1020
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040
  });
  promise.then((data) => {
      console.log(`queryContactsByPhoneNumber success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`queryContactsByPhoneNumber fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.queryContactsByEmail

queryContactsByEmail(email: string, callback: AsyncCallback<Array<Contact>>): void

根据email查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1041 1042 1043 1044
| 参数名   | 类型                                                  | 必填 | 说明                                   |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| email    | string                                                | 是   | 联系人的邮箱地址。                     |
| callback | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到的联系人对象数组。 |
O
ohos-lsw 已提交
1045 1046 1047

**示例:**

Z
zengyawen 已提交
1048
  ```js
O
ohos-lsw 已提交
1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069
  contact.queryContactsByEmail('xxx@email.com', (err, data) => {
      if (err) {
          console.log(`queryContactsByEmail callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContactsByEmail callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContactsByEmail

queryContactsByEmail(email: string, holder: Holder, callback: AsyncCallback<Array<Contact>>): void

根据email查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1070 1071 1072 1073 1074
| 参数名   | 类型                                                  | 必填 | 说明                                   |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| email    | string                                                | 是   | 联系人的邮箱地址。                     |
| holder   | [Holder](#holder)                                     | 是   | 创建联系人的应用信息。                 |
| callback | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到的联系人对象数组。 |
O
ohos-lsw 已提交
1075 1076 1077

**示例:**

Z
zengyawen 已提交
1078
  ```js
O
ohos-lsw 已提交
1079
  contact.queryContactsByEmail('xxx@email.com', {
Q
qian-nan-xu 已提交
1080 1081 1082
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103
  }, (err, data) => {
      if (err) {
          console.log(`queryContactsByEmail callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContactsByEmail callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContactsByEmail

queryContactsByEmail(email: string, attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void

根据email查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1104 1105 1106 1107 1108
| 参数名   | 类型                                                  | 必填 | 说明                                 |
| -------- | ----------------------------------------------------- | ---- | ------------------------------------ |
| email    | string                                                | 是   | 联系人的邮箱地址。                   |
| attrs    | [ContactAttributes](#contactattributes)               | 是   | 联系人的属性列表。                   |
| callback | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到联系人对象数组。 |
O
ohos-lsw 已提交
1109 1110 1111

**示例:**

Z
zengyawen 已提交
1112
  ```js
O
ohos-lsw 已提交
1113
  contact.queryContactsByEmail('xxx@email.com', {
Q
qian-nan-xu 已提交
1114
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135
  }, (err, data) => {
      if (err) {
          console.log(`queryContactsByEmail callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContactsByEmail callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContactsByEmail

queryContactsByEmail(email: string, holder: Holder, attrs: ContactAttributes, callback: AsyncCallback<Array<Contact>>): void

根据email查询联系人,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1136 1137 1138 1139 1140 1141
| 参数名   | 类型                                                  | 必填 | 说明                                 |
| -------- | ----------------------------------------------------- | ---- | ------------------------------------ |
| email    | string                                                | 是   | 联系人的邮箱地址。                   |
| holder   | [Holder](#holder)                                     | 是   | 创建联系人的应用信息。               |
| attrs    | [ContactAttributes](#contactattributes)               | 是   | 联系人的属性列表。                   |
| callback | AsyncCallback<Array<[Contact](#contact)>> | 是   | 回调函数,返回查询到联系人对象数组。 |
O
ohos-lsw 已提交
1142 1143 1144

**示例:**

Z
zengyawen 已提交
1145
  ```js
O
ohos-lsw 已提交
1146
  contact.queryContactsByEmail('xxx@email.com', {
Q
qian-nan-xu 已提交
1147 1148 1149
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
1150
  }, {
Q
qian-nan-xu 已提交
1151
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172
  }, (err, data) => {
      if (err) {
          console.log(`queryContactsByEmail callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryContactsByEmail callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryContactsByEmail

queryContactsByEmail(email: string, holder?: Holder, attrs?: ContactAttributes): Promise<Array<Contact>>

根据email查询联系人,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1173 1174 1175 1176 1177
| 参数名 | 类型                                    | 必填 | 说明                   |
| ------ | --------------------------------------- | ---- | ---------------------- |
| email  | string                                  | 是   | 联系人的邮箱地址。     |
| holder | [Holder](#holder)                       | 否   | 创建联系人的应用信息。 |
| attrs  | [ContactAttributes](#contactattributes) | 否   | 联系人的属性列表。     |
O
ohos-lsw 已提交
1178 1179

**返回值:**
H
update  
HelloCrease 已提交
1180 1181
| 类型                                            | 说明                                                |
| ----------------------------------------------- | --------------------------------------------------- |
O
ohos-lsw 已提交
1182 1183 1184 1185
| Promise<Array<[Contact](#contact)>> | 以Promise形式返回结果,返回查询到的联系人对象数组。 |

**示例:**

Z
zengyawen 已提交
1186
  ```js
O
ohos-lsw 已提交
1187
  let promise = contact.queryContactsByEmail('xxx@email.com', {
Q
qian-nan-xu 已提交
1188 1189 1190
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
1191
  }, {
Q
qian-nan-xu 已提交
1192
      attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
O
ohos-lsw 已提交
1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212
  });
  promise.then((data) => {
      console.log(`queryContactsByEmail success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`queryContactsByEmail fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.queryGroups

queryGroups(callback: AsyncCallback<Array<Group>>): void

查询联系人的所有群组,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1213 1214 1215
| 参数名   | 类型                                              | 必填 | 说明                                 |
| -------- | ------------------------------------------------- | ---- | ------------------------------------ |
| callback | AsyncCallback<Array<[Group](#group)>> | 是   | 回调函数,返回查询到的群组对象数组。 |
O
ohos-lsw 已提交
1216 1217 1218

**示例:**

Z
zengyawen 已提交
1219
  ```js
O
ohos-lsw 已提交
1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240
  contact.queryGroups((err, data) => {
      if (err) {
          console.log(`queryGroups callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryGroups callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryGroups

queryGroups(holder: Holder, callback: AsyncCallback<Array<Group>>): void

查询联系人的所有群组,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1241 1242 1243 1244
| 参数名   | 类型                                              | 必填 | 说明                                 |
| -------- | ------------------------------------------------- | ---- | ------------------------------------ |
| holder   | Holder                                            | 是   | 创建联系人的应用信息。               |
| callback | AsyncCallback<Array<[Group](#group)>> | 是   | 回调函数,返回查询到的群组对象数组。 |
O
ohos-lsw 已提交
1245 1246 1247

**示例:**

Z
zengyawen 已提交
1248
  ```js
O
ohos-lsw 已提交
1249
  contact.queryGroups({
Q
qian-nan-xu 已提交
1250 1251 1252
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273
  }, (err, data) => {
      if (err) {
          console.log(`queryGroups callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryGroups callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryGroups

queryGroups(holder?: Holder): Promise<Array<Group>>

查询联系人的所有群组,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1274 1275 1276
| 参数名 | 类型              | 必填 | 说明                   |
| ------ | ----------------- | ---- | ---------------------- |
| holder | [Holder](#holder) | 否   | 创建联系人的应用信息。 |
O
ohos-lsw 已提交
1277 1278

**返回值:**
H
update  
HelloCrease 已提交
1279 1280
| 类型                                        | 说明                                              |
| ------------------------------------------- | ------------------------------------------------- |
O
ohos-lsw 已提交
1281 1282 1283 1284
| Promise<Array<[Group](#group)>> | 以Promise形式返回结果,返回查询到的群组对象数组。 |

**示例:**

Z
zengyawen 已提交
1285
  ```js
O
ohos-lsw 已提交
1286
  let promise = contact.queryGroups({
Q
qian-nan-xu 已提交
1287 1288 1289
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309
  });
  promise.then((data) => {
      console.log(`queryGroups success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`queryGroups fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.queryHolders

queryHolders(callback: AsyncCallback<Array<Holder>>): void

查询所有创建联系人的应用信息,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1310 1311 1312
| 参数名   | 类型                                                | 必填 | 说明                                                 |
| -------- | --------------------------------------------------- | ---- | ---------------------------------------------------- |
| callback | AsyncCallback<Array<[Holder](#holder)>> | 是   | 回调函数,返回查询到的创建联系人应用信息的对象数组。 |
O
ohos-lsw 已提交
1313 1314 1315

**示例:**

Z
zengyawen 已提交
1316
  ```js
O
ohos-lsw 已提交
1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337
  contact.queryHolders((err, data) => {
      if (err) {
          console.log(`queryHolders callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryHolders callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryHolders

queryHolders(): Promise<Array<Holder>>

查询所有创建联系人的应用信息,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**返回值:**
H
update  
HelloCrease 已提交
1338 1339
| 类型                                          | 说明                                                         |
| --------------------------------------------- | ------------------------------------------------------------ |
O
ohos-lsw 已提交
1340 1341 1342 1343
| Promise<Array<[Holder](#holder)>> | 以Promise形式返回结果,返回查询到的创建联系人应用信息的对象数组。 |

**示例:**

Z
zengyawen 已提交
1344
  ```js
O
ohos-lsw 已提交
1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364
  let promise = contact.queryHolders();
  promise.then((data) => {
      console.log(`queryHolders success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`queryHolders fail: err->${JSON.stringify(err)}`);
  });
  ```


## contact.queryKey

queryKey(id: number, callback: AsyncCallback<string>): void

根据联系人的id查询联系人的key,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1365 1366 1367 1368
| 参数名   | 类型                        | 必填 | 说明                                    |
| -------- | --------------------------- | ---- | --------------------------------------- |
| id       | number                      | 是   | 联系人对象的id属性。                    |
| callback | AsyncCallback<string> | 是   | 回调函数,返回查询到的联系人对应的key。 |
O
ohos-lsw 已提交
1369 1370 1371

**示例:**

Z
zengyawen 已提交
1372
  ```js
O
ohos-lsw 已提交
1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393
  contact.queryKey(/*id*/1, (err, data) => {
      if (err) {
          console.log(`queryKey callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryKey callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryKey

queryKey(id: number, holder: Holder, callback: AsyncCallback<string>): void

根据联系人的id查询联系人的key,使用callback方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1394 1395 1396 1397 1398
| 参数名   | 类型                        | 必填 | 说明                                    |
| -------- | --------------------------- | ---- | --------------------------------------- |
| id       | number                      | 是   | 联系人对象的id属性。                    |
| holder   | [Holder](#holder)           | 是   | 创建联系人的应用信息。                  |
| callback | AsyncCallback<string> | 是   | 回调函数,返回查询到的联系人对应的key。 |
O
ohos-lsw 已提交
1399 1400 1401

**示例:**

Z
zengyawen 已提交
1402
  ```js
O
ohos-lsw 已提交
1403
  contact.queryKey(id, {
Q
qian-nan-xu 已提交
1404 1405 1406
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427
  }, (err, data) => {
      if (err) {
          console.log(`queryKey callback: err->${JSON.stringify(err)}`);
          return;
      }
      console.log(`queryKey callback: success data->${JSON.stringify(data)}`);
  });
  ```


## contact.queryKey

queryKey(id: number, holder?: Holder): Promise<string>

根据联系人的id查询联系人的key,使用Promise方式作为异步方法。

**需要权限**:ohos.permission.READ_CONTACTS

**系统能力**:SystemCapability.Applications.ContactsData

**参数:**
H
update  
HelloCrease 已提交
1428 1429 1430 1431
| 参数名 | 类型              | 必填 | 说明                   |
| ------ | ----------------- | ---- | ---------------------- |
| id     | number            | 是   | 联系人对象的id属性。   |
| holder | [Holder](#holder) | 否   | 创建联系人的应用信息。 |
O
ohos-lsw 已提交
1432 1433

**返回值:**
H
update  
HelloCrease 已提交
1434 1435
| 类型                  | 说明                                                 |
| --------------------- | ---------------------------------------------------- |
O
ohos-lsw 已提交
1436 1437 1438 1439
| Promise<string> | 以Promise形式返回结果,返回查询到的联系人对应的key。 |

**示例:**

Z
zengyawen 已提交
1440
  ```js
O
ohos-lsw 已提交
1441
  let promise = contact.queryKey(id, {
Q
qian-nan-xu 已提交
1442 1443 1444
      holderId: 0,
      bundleName: "",
      displayName: ""
O
ohos-lsw 已提交
1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461
  });
  promise.then((data) => {
      console.log(`queryKey success: data->${JSON.stringify(data)}`);
  }).catch((err) => {
      console.error(`queryKey fail: err->${JSON.stringify(err)}`);
  });
  ```


## Contact

联系人对象类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

### 常量

H
update  
HelloCrease 已提交
1462 1463 1464
| 名称               | 值   | 说明             |
| ------------------ | ---- | ---------------- |
| INVALID_CONTACT_ID | -1   | 默认联系人的id。 |
O
ohos-lsw 已提交
1465 1466 1467 1468


### 属性

H
update  
HelloCrease 已提交
1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487
| 名称              | 参数类型                                | 可读 | 可写 | 说明                                   |
| ----------------- | --------------------------------------- | ---- | ---- | -------------------------------------- |
| id                | number                                  | 是   | 否   | 联系人的id。                           |
| key               | string                                  | 是   | 否   | 联系人的key。                          |
| contactAttributes | [ContactAttributes](#contactattributes) | 是   | 是   | 联系人的属性列表。                     |
| emails            | [Email](#email)[]                       | 是   | 是   | 联系人的邮箱地址列表。                 |
| events            | [Event](#event)[]                       | 是   | 是   | 联系人的生日、周年纪念等重要日期列表。 |
| groups            | [Group](#group)[]                       | 是   | 是   | 联系人的群组列表。                     |
| imAddresses       | [ImAddress](#imaddress)[]               | 是   | 是   | 联系人的即时消息地址列表。             |
| phoneNumbers      | [PhoneNumber](#phonenumber)[]           | 是   | 是   | 联系人的电话号码列表。                 |
| portrait          | [Portrait](#portrait)                   | 是   | 是   | 联系人的头像。                         |
| postalAddresses   | [PostalAddress](#postaladdress)[]       | 是   | 是   | 联系人的邮政地址列表。                 |
| relations         | [Relation](#relation)[]                 | 是   | 是   | 联系人的关系列表。                     |
| sipAddresses      | [SipAddress](#sipaddress)[]             | 是   | 是   | 联系人的会话发起协议(SIP)地址列表。  |
| websites          | [Website](#website)[]                   | 是   | 是   | 联系人的网站列表。                     |
| name              | [Name](#name)                           | 是   | 是   | 联系人的姓名。                         |
| nickName          | [NickName](#nickname)                   | 是   | 是   | 联系人的昵称。                         |
| note              | [Note](#note)                           | 是   | 是   | 联系人的备注。                         |
| organization      | [Organization](#organization)           | 是   | 是   | 联系人的组织信息。                     |
O
ohos-lsw 已提交
1488 1489 1490 1491 1492 1493 1494


**对象创建示例:**

使用JSON格式创建联系人数据:


1495
```js
O
ohos-lsw 已提交
1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512
let myContact = {
    phoneNumbers: [{
        phoneNumber: "138xxxxxxxx"
    }],
    name: {
        fullName: "fullName",
        namePrefix: "namePrefix"
    },
    nickName: {
        nickName: "nickName"
    }
};
```


  或使用new一个Contact对象的方式创建数据:

Z
zengyawen 已提交
1513
```js
O
ohos-lsw 已提交
1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530
let myContact = new contact.Contact();
let name = new contact.Name();
name.fullName = "fullName";
let phoneNumber = new contact.PhoneNumber();
phoneNumber.phoneNumber = "138xxxxxxxx";
myContact.name = name;
myContact.phoneNumbers = [phoneNumber];
```


## ContactAttributes

联系人属性列表,一般作为入参用来标识希望查询的联系人属性。
当传入为null时,默认查询全部属性。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

H
update  
HelloCrease 已提交
1531 1532 1533
| 名称       | 参数类型                  | 可读 | 可写 | 说明             |
| ---------- | ------------------------- | ---- | ---- | ---------------- |
| attributes | [Attribute](#attribute)[] | 是   | 是   | 联系人属性列表。 |
O
ohos-lsw 已提交
1534 1535 1536 1537 1538 1539 1540


**对象创建示例:**

使用JSON格式创建数据:


1541
```js
O
ohos-lsw 已提交
1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553
let contactAttributes = {
    attributes: [
        contact.Attribute.ATTR_EMAIL,
        contact.Attribute.ATTR_NAME,
        contact.Attribute.ATTR_PHONE
    ]
};
```

或使用new一个ContactAttributes对象的方式创建数据:


Z
zengyawen 已提交
1554
```js
O
ohos-lsw 已提交
1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565
let contactAttributes = new contact.ContactAttributes();
contactAttributes.attributes = ["ATTR_EMAIL"];
```


## Attribute

枚举,联系人属性列表。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

H
update  
HelloCrease 已提交
1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581
| 名称                  | 说明                               |
| --------------------- | ---------------------------------- |
| ATTR_CONTACT_EVENT    | 联系人的生日、周年纪念等重要日期。 |
| ATTR_EMAIL            | 联系人的邮箱地址。                 |
| ATTR_GROUP_MEMBERSHIP | 联系人的群组。                     |
| ATTR_IM               | 联系人的即时消息地址。             |
| ATTR_NAME             | 联系人的姓名。                     |
| ATTR_NICKNAME         | 联系人的昵称。                     |
| ATTR_NOTE             | 联系人的备注。                     |
| ATTR_ORGANIZATION     | 联系人的组织信息。                 |
| ATTR_PHONE            | 联系人的电话号码。                 |
| ATTR_PORTRAIT         | 联系人的头像。                     |
| ATTR_POSTAL_ADDRESS   | 联系人的邮政地址。                 |
| ATTR_RELATION         | 联系人的关系。                     |
| ATTR_SIP_ADDRESS      | 联系人的会话发起协议(SIP)地址。  |
| ATTR_WEBSITE          | 联系人的网站。                     |
O
ohos-lsw 已提交
1582 1583 1584 1585 1586 1587


**对象创建示例:**

使用JSON格式创建数据:

1588
```js
O
ohos-lsw 已提交
1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600
let attributes = [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME, contact.Attribute.ATTR_PHONE];
```


## Email

联系人的邮箱。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

### 常量

H
update  
HelloCrease 已提交
1601 1602 1603 1604 1605 1606 1607
| 名称             | 值   | 说明             |
| ---------------- | ---- | ---------------- |
| CUSTOM_LABEL     | 0    | 自定义邮箱类型。 |
| EMAIL_HOME       | 1    | 家庭邮箱类型。   |
| EMAIL_WORK       | 2    | 工作邮箱类型。   |
| EMAIL_OTHER      | 3    | 其它邮箱类型。   |
| INVALID_LABEL_ID | -1   | 无效邮箱类型。   |
O
ohos-lsw 已提交
1608 1609 1610 1611


### 属性

H
update  
HelloCrease 已提交
1612 1613 1614 1615 1616 1617
| 名称        | 参数类型 | 可读 | 可写 | 说明             |
| ----------- | -------- | ---- | ---- | ---------------- |
| email       | string   | 是   | 是   | 邮箱地址。       |
| labelName   | string   | 是   | 是   | 邮箱的类型名称。 |
| displayName | string   | 是   | 是   | 邮箱的显示名称。 |
| labelId     | number   | 是   | 是   | 邮箱的类型。     |
O
ohos-lsw 已提交
1618 1619 1620 1621 1622 1623


**对象创建示例:**

  使用JSON格式创建数据:

1624
```js
O
ohos-lsw 已提交
1625 1626 1627 1628 1629 1630 1631 1632 1633
let email = {
    email: "xxx@email.com",
    displayName: "displayName"
}
```


  或使用new一个Email对象的方式创建数据:

Z
zengyawen 已提交
1634
```js
O
ohos-lsw 已提交
1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645
let email = new contact.Email();
email.email = "xxx@email.com";
```


## Holder

创建联系人的应用信息类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

H
update  
HelloCrease 已提交
1646 1647 1648 1649 1650
| 名称        | 参数类型 | 可读 | 可写 | 说明       |
| ----------- | -------- | ---- | ---- | ---------- |
| bundleName  | string   | 是   | 否   | 包名。     |
| displayName | string   | 是   | 否   | 应用名称。 |
| holderId    | number   | 是   | 是   | 应用id。   |
O
ohos-lsw 已提交
1651 1652 1653 1654 1655 1656


**对象创建示例:**

  使用JSON格式创建数据:

1657
```js
O
ohos-lsw 已提交
1658 1659 1660 1661 1662 1663 1664
let holder = {
  holderId: 0
};
```

  或使用new一个Holder对象的方式创建数据:

Z
zengyawen 已提交
1665
```js
O
ohos-lsw 已提交
1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678
let holder = new contact.Holder();
holder.holderId = 0;
```


## Event

联系人事件类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

### 常量

H
update  
HelloCrease 已提交
1679 1680 1681 1682 1683 1684 1685
| 名称              | 值   | 说明               |
| ----------------- | ---- | ------------------ |
| CUSTOM_LABEL      | 0    | 自定义事件类型。   |
| EVENT_ANNIVERSARY | 1    | 周年纪念事件类型。 |
| EVENT_OTHER       | 2    | 其它事件类型。     |
| EVENT_BIRTHDAY    | 3    | 生日事件类型。     |
| INVALID_LABEL_ID  | -1   | 无效事件类型。     |
O
ohos-lsw 已提交
1686 1687 1688 1689


### 属性

H
update  
HelloCrease 已提交
1690 1691 1692 1693 1694
| 名称      | 参数类型 | 可读 | 可写 | 说明           |
| --------- | -------- | ---- | ---- | -------------- |
| eventDate | string   | 是   | 是   | 事件的日期。   |
| labelName | string   | 是   | 是   | 事件类型名称。 |
| labelId   | number   | 是   | 是   | 事件类型。     |
O
ohos-lsw 已提交
1695 1696 1697 1698 1699 1700


**对象创建示例:**

  使用JSON格式创建数据:

1701
```js
O
ohos-lsw 已提交
1702 1703 1704 1705 1706 1707 1708
let event = {
    eventDate: "xxxxxx"
};
```

  或使用new一个Event对象的方式创建数据:

Z
zengyawen 已提交
1709
```js
O
ohos-lsw 已提交
1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720
let event = new contact.Event();
event.eventDate = "xxxxxx";
```


## Group

联系人的群组类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

H
update  
HelloCrease 已提交
1721 1722 1723 1724
| 名称    | 参数类型 | 可读 | 可写 | 说明               |
| ------- | -------- | ---- | ---- | ------------------ |
| groupId | number   | 是   | 是   | 联系人群组的id。   |
| title   | string   | 是   | 是   | 联系人群组的名称。 |
O
ohos-lsw 已提交
1725 1726 1727 1728 1729 1730


**对象创建示例:**

  使用JSON格式创建数据:

1731
```js
O
ohos-lsw 已提交
1732 1733 1734 1735 1736 1737 1738 1739
let group = {
    groupId: 1,
    title: "title"
};
```

  或使用new一个Group对象的方式创建数据:

Z
zengyawen 已提交
1740
```js
O
ohos-lsw 已提交
1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753
let group = new contact.Group();
group.title = "title";
```


## ImAddress

联系人的即时消息地址。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

### 常量

H
update  
HelloCrease 已提交
1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764
| 名称             | 值   | 说明                 |
| ---------------- | ---- | -------------------- |
| CUSTOM_LABEL     | -1   | 自定义即时消息类型。 |
| IM_AIM           | 0    | AIM即时消息类型。    |
| IM_MSN           | 1    | MSN即时消息类型。    |
| IM_YAHOO         | 2    | YAHOO即时消息类型。  |
| IM_SKYPE         | 3    | SKYPE即时消息类型。  |
| IM_QQ            | 4    | QQ即时消息类型。     |
| IM_ICQ           | 6    | ICQ即时消息类型。    |
| IM_JABBER        | 7    | JABBER即时消息类型。 |
| INVALID_LABEL_ID | -2   | 无效的即时消息类型。 |
O
ohos-lsw 已提交
1765 1766 1767 1768


### 属性

H
update  
HelloCrease 已提交
1769 1770 1771 1772 1773
| 名称      | 参数类型 | 可读 | 可写 | 说明               |
| --------- | -------- | ---- | ---- | ------------------ |
| imAddress | string   | 是   | 是   | 即时消息地址。     |
| labelName | string   | 是   | 是   | 即时消息类型名称。 |
| labelId   | number   | 是   | 是   | 即时消息类型。     |
O
ohos-lsw 已提交
1774 1775 1776 1777 1778 1779


**对象创建示例:**

  使用JSON格式创建数据:

1780
```js
O
ohos-lsw 已提交
1781 1782 1783 1784 1785 1786 1787 1788 1789
let imAddress = {
    imAddress: "imAddress",
    labelName: "labelName"
};
```


  或使用new一个ImAddress对象的方式创建数据:

Z
zengyawen 已提交
1790
```js
O
ohos-lsw 已提交
1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801
let imAddress = new contact.ImAddress();
imAddress.imAddress = "imAddress";
```


## Name

联系人的名字类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

H
update  
HelloCrease 已提交
1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812
| 名称               | 参数类型 | 可读 | 可写 | 说明                        |
| ------------------ | -------- | ---- | ---- | --------------------------- |
| familyName         | string   | 是   | 是   | 联系人的家庭姓名。          |
| familyNamePhonetic | string   | 是   | 是   | 联系人的家庭姓名拼音。      |
| fullName           | string   | 是   | 是   | 联系人的全名。              |
| givenName          | string   | 是   | 是   | 联系人的名称(firstName)。 |
| givenNamePhonetic  | string   | 是   | 是   | 联系人的名称拼音。          |
| middleName         | string   | 是   | 是   | 联系人的中间名。            |
| middleNamePhonetic | string   | 是   | 是   | 联系人的中间名拼音。        |
| namePrefix         | string   | 是   | 是   | 联系人的姓名前缀。          |
| nameSuffix         | string   | 是   | 是   | 联系人的姓名后缀。          |
O
ohos-lsw 已提交
1813 1814 1815 1816 1817 1818


**对象创建示例:**

  使用JSON格式创建数据:

1819
```js
O
ohos-lsw 已提交
1820 1821 1822 1823 1824 1825 1826 1827
let name = {
    familyName: "familyName",
    fullName: "fullName"
};
```

  或使用new一个name对象的方式创建数据:

Z
zengyawen 已提交
1828
```js
O
ohos-lsw 已提交
1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840
let name = new contact.Name();
name.familyName = "familyName";
name.fullName = "fullName";
```


## NickName

联系人的昵称类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

H
update  
HelloCrease 已提交
1841 1842 1843
| 名称     | 参数类型 | 可读 | 可写 | 说明           |
| -------- | -------- | ---- | ---- | -------------- |
| nickName | string   | 是   | 是   | 联系人的昵称。 |
O
ohos-lsw 已提交
1844 1845 1846 1847 1848 1849


**对象创建示例:**

  使用JSON格式创建数据:

1850
```js
O
ohos-lsw 已提交
1851 1852 1853 1854 1855 1856 1857
let nickName = {
    nickName: "nickName"
};
```

  或使用new一个NickName对象的方式创建数据:

Z
zengyawen 已提交
1858
```js
O
ohos-lsw 已提交
1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869
let nickName = new contact.NickName();
nickName.nickName = "nickName";
```


## Note

联系人的备注类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

H
update  
HelloCrease 已提交
1870 1871 1872
| 名称        | 参数类型 | 可读 | 可写 | 说明               |
| ----------- | -------- | ---- | ---- | ------------------ |
| noteContent | string   | 是   | 是   | 联系人的备注内容。 |
O
ohos-lsw 已提交
1873 1874 1875 1876 1877 1878


**对象创建示例:**

  使用JSON格式创建数据:

1879
```js
O
ohos-lsw 已提交
1880 1881 1882 1883 1884 1885 1886
let note = {
    noteContent: "noteContent"
};
```

  或使用new一个Note对象的方式创建数据:

Z
zengyawen 已提交
1887
```js
O
ohos-lsw 已提交
1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898
let note = new contact.Note();
note.noteContent = "noteContent";
```


## Organization

联系人的组织类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

H
update  
HelloCrease 已提交
1899 1900 1901 1902
| 名称  | 参数类型 | 可读 | 可写 | 说明       |
| ----- | -------- | ---- | ---- | ---------- |
| name  | string   | 是   | 是   | 组织名称。 |
| title | string   | 是   | 是   | 组织标题。 |
O
ohos-lsw 已提交
1903 1904 1905 1906 1907 1908


**对象创建示例:**

  使用JSON格式创建数据:

1909
```js
O
ohos-lsw 已提交
1910 1911 1912 1913 1914 1915 1916 1917
let organization = {
    name: "name",
    title: "title"
};
```

  或使用new一个Organization对象的方式创建数据:

Z
zengyawen 已提交
1918
```js
O
ohos-lsw 已提交
1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932
let organization = new contact.Organization();
organization.name = "name";
organization.title = "title";
```


## PhoneNumber

联系人电话号码类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

### 常量

H
update  
HelloCrease 已提交
1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956
| 名称             | 值   | 说明                                             |
| ---------------- | ---- | ------------------------------------------------ |
| CUSTOM_LABEL     | 0    | 自定义电话类型。                                 |
| NUM_HOME         | 1    | 家庭电话类型。                                   |
| NUM_MOBILE       | 2    | 移动电话类型。                                   |
| NUM_WORK         | 3    | 工作电话类型。                                   |
| NUM_FAX_WORK     | 4    | 工作传真电话类型。                               |
| NUM_FAX_HOME     | 5    | 家庭传真电话类型。                               |
| NUM_PAGER        | 6    | 寻呼机电话类型。                                 |
| NUM_OTHER        | 7    | 其它电话类型。                                   |
| NUM_CALLBACK     | 8    | 回呼电话类型。                                   |
| NUM_CAR          | 9    | 车机电话类型。                                   |
| NUM_COMPANY_MAIN | 10   | 公司电话类型。                                   |
| NUM_ISDN         | 11   | 综合业务数字网(ISDN)电话类型。                 |
| NUM_MAIN         | 12   | 主电话类型。                                     |
| NUM_OTHER_FAX    | 13   | 其它传真类型。                                   |
| NUM_RADIO        | 14   | 无线电话类型。                                   |
| NUM_TELEX        | 15   | 电传电话类型。                                   |
| NUM_TTY_TDD      | 16   | 电传打字机(TTY)或测试驱动开发(TDD)电话类型。 |
| NUM_WORK_MOBILE  | 17   | 工作移动电话类型。                               |
| NUM_WORK_PAGER   | 18   | 工作寻呼机电话类型。                             |
| NUM_ASSISTANT    | 19   | 助理电话类型。                                   |
| NUM_MMS          | 20   | 彩信电话类型。                                   |
| INVALID_LABEL_ID | -1   | 无效电话类型。                                   |
O
ohos-lsw 已提交
1957 1958 1959 1960


### 属性

H
update  
HelloCrease 已提交
1961 1962 1963 1964 1965
| 名称        | 参数类型 | 可读 | 可写 | 说明               |
| ----------- | -------- | ---- | ---- | ------------------ |
| labelName   | string   | 是   | 是   | 电话号码类型名称。 |
| phoneNumber | string   | 是   | 是   | 电话号码。         |
| labelId     | number   | 是   | 是   | 电话号码类型。     |
O
ohos-lsw 已提交
1966 1967 1968 1969 1970 1971


**对象创建示例:**

  使用JSON格式创建数据:

1972
```js
O
ohos-lsw 已提交
1973 1974 1975 1976 1977 1978 1979 1980
let phoneNumber = {
    phoneNumber: "138xxxxxxxx",
    labelId: contact.PhoneNumber.NUM_HOME
};
```

  或使用new一个PhoneNumber对象的方式创建数据:

Z
zengyawen 已提交
1981
```js
O
ohos-lsw 已提交
1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992
let phoneNumber = new contact.PhoneNumber();
phoneNumber.phoneNumber = "138xxxxxxxx";
```


## Portrait

联系人的头像类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

H
update  
HelloCrease 已提交
1993 1994 1995
| 名称 | 参数类型 | 可读 | 可写 | 说明           |
| ---- | -------- | ---- | ---- | -------------- |
| uri  | string   | 是   | 是   | 联系人的头像。 |
O
ohos-lsw 已提交
1996 1997 1998 1999 2000 2001


**对象创建示例:**

  使用JSON格式创建数据:

2002
```js
O
ohos-lsw 已提交
2003 2004 2005 2006 2007 2008 2009
let portrait = {
    uri: "uri"
};
```

  或使用new一个Portrait对象的方式创建数据:

Z
zengyawen 已提交
2010
```js
O
ohos-lsw 已提交
2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023
let portrait = new contact.Portrait();
portrait.uri = "uri";
```


## PostalAddress

联系人的邮政地址类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

### 常量

H
update  
HelloCrease 已提交
2024 2025 2026 2027 2028 2029 2030
| 名称             | 值   | 说明                 |
| ---------------- | ---- | -------------------- |
| CUSTOM_LABEL     | 0    | 自定义邮政地址类型。 |
| ADDR_HOME        | 1    | 家庭地址类型。       |
| ADDR_WORK        | 2    | 工作地址类型。       |
| ADDR_OTHER       | 3    | 其它地址类型。       |
| INVALID_LABEL_ID | -1   | 无效地址类型。       |
O
ohos-lsw 已提交
2031 2032 2033 2034


### 属性

H
update  
HelloCrease 已提交
2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046
| 名称          | 参数类型 | 可读 | 可写 | 说明                       |
| ------------- | -------- | ---- | ---- | -------------------------- |
| city          | string   | 是   | 是   | 联系人所在的城市。         |
| country       | string   | 是   | 是   | 联系人所在的国家。         |
| labelName     | string   | 是   | 是   | 邮政地址类型名称。         |
| neighborhood  | string   | 是   | 是   | 联系人的邻居。             |
| pobox         | string   | 是   | 是   | 联系人的邮箱。             |
| postalAddress | string   | 是   | 是   | 联系人的邮政地址。         |
| postcode      | string   | 是   | 是   | 联系人所在区域的邮政编码。 |
| region        | string   | 是   | 是   | 联系人所在的区域。         |
| street        | string   | 是   | 是   | 联系人所在的街道。         |
| labelId       | number   | 是   | 是   | 邮政地址名称。             |
O
ohos-lsw 已提交
2047 2048 2049 2050 2051 2052


**对象创建示例:**

  使用JSON格式创建数据:

2053
```js
O
ohos-lsw 已提交
2054 2055 2056 2057 2058 2059 2060
let postalAddress = {
    city: "city"
};
```

  或使用new一个PostalAddress对象的方式创建数据:

Z
zengyawen 已提交
2061
```js
O
ohos-lsw 已提交
2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074
let postalAddress = new contact.PostalAddress();
postalAddress.city = "city";
```


## Relation

联系人的关系类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

### 常量

H
update  
HelloCrease 已提交
2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092
| 名称                      | 值   | 说明               |
| ------------------------- | ---- | ------------------ |
| CUSTOM_LABEL              | 0    | 自定义关系类型。   |
| RELATION_ASSISTANT        | 1    | 助手关系类型。     |
| RELATION_BROTHER          | 2    | 兄弟关系类型。     |
| RELATION_CHILD            | 3    | 子女关系类型。     |
| RELATION_DOMESTIC_PARTNER | 4    | 同居同伴关系类型。 |
| RELATION_FATHER           | 5    | 父亲关系类型。     |
| RELATION_FRIEND           | 6    | 朋友关系类型。     |
| RELATION_MANAGER          | 7    | 管理者关系类型。   |
| RELATION_MOTHER           | 8    | 母亲关系类型。     |
| RELATION_PARENT           | 9    | 父母关系类型。     |
| RELATION_PARTNER          | 10   | 合作伙伴关系类型。 |
| RELATION_REFERRED_BY      | 11   | 推荐人关系类型。   |
| RELATION_RELATIVE         | 12   | 亲属关系类型。     |
| RELATION_SISTER           | 13   | 姐妹关系类型。     |
| RELATION_SPOUSE           | 14   | 配偶关系类型。     |
| INVALID_LABEL_ID          | -1   | 无效的关系类型。   |
O
ohos-lsw 已提交
2093 2094 2095 2096


### 属性

H
update  
HelloCrease 已提交
2097 2098 2099 2100 2101
| 名称         | 参数类型 | 可读 | 可写 | 说明           |
| ------------ | -------- | ---- | ---- | -------------- |
| labelName    | string   | 是   | 是   | 关系类型名称。 |
| relationName | string   | 是   | 是   | 关系名称。     |
| labelId      | number   | 是   | 是   | 关系类型。     |
O
ohos-lsw 已提交
2102 2103 2104 2105 2106 2107


**对象创建示例:**

  使用JSON格式创建数据:

2108
```js
O
ohos-lsw 已提交
2109 2110 2111 2112 2113 2114 2115 2116
let relation = {
    relationName: "relationName",
    labelId: contact.Relation.RELATION_ASSISTANT
};
```

  或使用new一个Relation对象的方式创建数据:

Z
zengyawen 已提交
2117
```js
O
ohos-lsw 已提交
2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131
let relation = new contact.Relation();
relation.relationName = "relationName";
relation.labelId = contact.Relation.RELATION_ASSISTANT;
```


## SipAddress

联系人的会话发起协议(SIP)地址类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

### 常量

H
update  
HelloCrease 已提交
2132 2133 2134 2135 2136 2137 2138
| 名称             | 值   | 说明                                |
| ---------------- | ---- | ----------------------------------- |
| CUSTOM_LABEL     | 0    | 自定义会话发起协议(SIP)地址类型。 |
| SIP_HOME         | 1    | 家庭会话发起协议(SIP)地址类型。   |
| SIP_WORK         | 2    | 工作会话发起协议(SIP)地址类型。   |
| SIP_OTHER        | 3    | 其它会话发起协议(SIP)地址类型。   |
| INVALID_LABEL_ID | -1   | 无效会话发起协议(SIP)地址类型。   |
O
ohos-lsw 已提交
2139 2140 2141 2142


### 属性

H
update  
HelloCrease 已提交
2143 2144 2145 2146 2147
| 名称       | 参数类型 | 可读 | 可写 | 说明                              |
| ---------- | -------- | ---- | ---- | --------------------------------- |
| labelName  | string   | 是   | 是   | 会话发起协议(SIP)地址类型名称。 |
| sipAddress | string   | 是   | 是   | 会话发起协议(SIP)地址。         |
| labelId    | number   | 是   | 是   | 会话发起协议(SIP)地址类型。     |
O
ohos-lsw 已提交
2148 2149 2150 2151 2152

**对象创建示例:**

  使用JSON格式创建数据:

2153
```js
O
ohos-lsw 已提交
2154 2155 2156 2157 2158 2159 2160
var sipAddress = {
    sipAddress: "sipAddress"
};
```

  或使用new一个SipAddress对象的方式创建数据:

Z
zengyawen 已提交
2161
```js
O
ohos-lsw 已提交
2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172
let sipAddress = new contact.SipAddress();
sipAddress.sipAddress = "sipAddress";
```


## Website

联系人的网站信息类。

**系统能力**:以下各项对应的系统能力均为SystemCapability.Applications.ContactsData。

H
update  
HelloCrease 已提交
2173 2174 2175
| 名称    | 参数类型 | 可读 | 可写 | 说明               |
| ------- | -------- | ---- | ---- | ------------------ |
| website | string   | 是   | 是   | 联系人的网站信息。 |
O
ohos-lsw 已提交
2176 2177 2178 2179 2180 2181


**对象创建示例:**

  使用JSON格式创建数据:

2182
```js
O
ohos-lsw 已提交
2183 2184 2185 2186 2187 2188 2189
let website = {
    website: "website"
};
```

  或使用new一个Website对象的方式创建数据:

Z
zengyawen 已提交
2190
```js
O
ohos-lsw 已提交
2191 2192
let website = new contact.Website();
website.website = "website";
H
update  
HelloCrease 已提交
2193
```