HarmonyOS API：@ohos.contact (联系人)

joytrian

发布于 2023-4-6 17:42

6072浏览

0收藏

版本：v3.1 Beta

@ohos.contact (联系人)

更新时间: 2023-02-17 09:19

本模块提供联系人管理能力，包括添加联系人、删除联系人、更新联系人等

说明

本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

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

contact.addContact

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

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

需要权限：ohos.permission.WRITE_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
contact	Contact	是	联系人信息。
callback	AsyncCallback<number>	是	回调函数，返回添加的联系人id。

示例：

contact.addContact({
    name: {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)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

contact.addContact

addContact(contact: Contact): Promise<number>

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

需要权限：ohos.permission.WRITE_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
contact	Contact	是	联系人信息。

返回值：

类型	说明
Promise<number>	以Promise形式返回结果，返回添加的联系人id。

示例：

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)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.

contact.deleteContact

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

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

需要权限：ohos.permission.WRITE_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
key	string	是	联系人key值，一个联系人对应一个key。
callback	AsyncCallback<void>	是	回调函数，返回删除联系人的结果。

示例：

contact.deleteContact('xxx', (err) => {
    if (err) {
        console.log(`deleteContact callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log('deleteContact success');
});1.
2.
3.
4.
5.
6.
7.

contact.deleteContact

deleteContact(key: string): Promise<void>

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

需要权限：ohos.permission.WRITE_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
key	string	是	联系人的key值，一个联系人对应一个key。

返回值：

类型	说明
Promise<void>	以Promise形式返回结果，返回删除联系人的结果。

示例：

let promise = contact.deleteContact('xxx');
promise.then(() => {
    console.log(`deleteContact success`);
}).catch((err) => {
    console.error(`deleteContact fail: err->${JSON.stringify(err)}`);
});1.
2.
3.
4.
5.
6.

contact.updateContact

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

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

需要权限：ohos.permission.WRITE_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
contact	Contact	是	联系人信息。
callback	AsyncCallback<void>	是	回调函数，返回更新联系人的更新结果。

示例：

contact.updateContact({
    name: {fullName: 'xxx'},
    phoneNumbers: [{phoneNumber: '138xxxxxxxx'}]
}, (err) => {
    if (err) {
        console.log('updateContact callback: err->${JSON.stringify(err)}');
        return;
    }
    console.log('updateContact success');
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

contact.updateContact

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

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

需要权限：ohos.permission.WRITE_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
contact	Contact	是	联系人信息。
attrs	ContactAttributes	是	联系人的属性列表。
callback	AsyncCallback<void>	是	回调函数，返回更新联系人的更新结果。

示例：

contact.updateContact({
    name: {fullName: 'xxx'},
    phoneNumbers: [{phoneNumber: '138xxxxxxxx'}]
}, {
    attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
}, (err) => {
    if (err) {
        console.log('updateContact callback: err->${JSON.stringify(err)}');
        return;
    }
    console.log('updateContact success');
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

contact.updateContact

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

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

需要权限：ohos.permission.WRITE_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
contact	Contact	是	联系人信息。
attrs	ContactAttributes	否	联系人的属性列表。

返回值：

类型	说明
Promise<void>	以Promise形式返回结果，返回更新联系人的更新结果。

示例：

let promise = contact.updateContact({
    name: {fullName: 'xxx'},
    phoneNumbers: [{phoneNumber: '138xxxxxxxx'}]
}, {
    attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
});
promise.then(() => {
    console.log('updateContact success');
}).catch((err) => {
    console.error(`updateContact fail: err->${JSON.stringify(err)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

contact.isLocalContact

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
id	number	是	联系人对象的id属性，一个联系人对应一个id。
callback	AsyncCallback<boolean>	是	回调函数，返回布尔值。true代表联系人id在本地电话簿中，false则代表联系人id不在本地电话簿中。

示例：

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)}`);
});1.
2.
3.
4.
5.
6.
7.

contact.isLocalContact

isLocalContact(id: number): Promise<boolean>

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
id	number	是	联系人对象的id属性，一个联系人对应一个id。

返回值：

类型	说明
Promise<boolean>	以Promise形式返回结果，返回布尔值。true代表联系人id在本地电话簿中，false则代表联系人id不在本地电话簿中。

示例：

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)}`);
});1.
2.
3.
4.
5.
6.

contact.isMyCard

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
id	number	是	联系人对象的id属性。
callback	AsyncCallback<boolean>	是	回调函数，返回是否为“我的名片”的布尔值。true代表此联系人是“我的名片”，false则代表不是。

示例：

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)}`);
});1.
2.
3.
4.
5.
6.
7.

contact.isMyCard

isMyCard(id: number): Promise<boolean>

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
id	number	是	联系人对象的id属性。

返回值：

类型	说明
Promise<boolean>	以Promise形式返回结果，返回是否为“我的名片”的布尔值。true代表此联系人是“我的名片”，false则代表不是。

示例：

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)}`);
});1.
2.
3.
4.
5.
6.

contact.queryMyCard

queryMyCard(callback: AsyncCallback<Contact>): void

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Contact>	是	回调函数，返回“我的名片”信息。

示例：

contact.queryMyCard((err, data) => {
    if (err) {
        console.log(`queryMyCard callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log(`queryMyCard callback: success data->${JSON.stringify(data)}`);
});1.
2.
3.
4.
5.
6.
7.

contact.queryMyCard

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
attrs	ContactAttributes	是	联系人的属性列表。
callback	AsyncCallback<Contact>	是	回调函数，返回“我的名片”信息。

示例：

contact.queryMyCard({
    attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
}, (err, data) => {
    if (err) {
        console.log(`queryMyCard callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log(`queryMyCard callback: success data->${JSON.stringify(data)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.

contact.queryMyCard

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
attrs	ContactAttributes	否	联系人的属性列表。

返回值：

类型	说明
Promise<Contact>	以Promise形式返回结果，返回“我的名片”信息。

示例：

let promise = contact.queryMyCard({
    attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
});
promise.then((data) => {
    console.log(`queryMyCard success: data->${JSON.stringify(data)}`);
}).catch((err) => {
    console.error(`queryMyCard fail: err->${JSON.stringify(err)}`);
});1.
2.
3.
4.
5.
6.
7.
8.

contact.selectContact

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.Contacts

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Array<Contact>>	是	回调函数，返回选择的联系人对象数组。

示例：

contact.selectContact((err, data) => {
    if (err) {
        console.log(`selectContact callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log(`selectContact callback: success data->${JSON.stringify(data)}`);
});1.
2.
3.
4.
5.
6.
7.

contact.selectContact

selectContact(): Promise<Array<Contact>>

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.Contacts

返回值：

类型	说明
Promise<Array<Contact>>	以Promise形式返回结果，返回选择的联系人对象数组。

示例：

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)}`);
});1.
2.
3.
4.
5.
6.

contact.queryContact

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
key	string	是	联系人的key值，一个联系人对应一个key。
callback	AsyncCallback<Contact>	是	回调函数，返回查询的联系人对象。

示例：

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)}`);
});1.
2.
3.
4.
5.
6.
7.

contact.queryContact

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
key	string	是	联系人的key值，一个联系人对应一个key。
holder	Holder	是	创建联系人的应用信息。
callback	AsyncCallback<Contact>	是	回调函数，返回查询的联系人对象。

示例：

contact.queryContact('xxx', {
    holderId: 0,
    bundleName: "",
    displayName: ""
}, (err, data) => {
    if (err) {
        console.log(`queryContact callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log(`queryContact callback: success data->${JSON.stringify(data)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

contact.queryContact

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
key	string	是	联系人的key值，一个联系人对应一个key。
attrs	ContactAttributes	是	联系人的属性列表。
callback	AsyncCallback<Contact>	是	回调函数，返回查询的联系人对象。

示例：

contact.queryContact('xxx', {
    attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
}, (err, data) => {
    if (err) {
        console.log(`queryContact callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log(`queryContact callback: success data->${JSON.stringify(data)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.

contact.queryContact

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
key	string	是	联系人的key值，一个联系人对应一个key。
holder	Holder	是	创建联系人的应用信息。
attrs	ContactAttributes	是	联系人的属性列表。
callback	AsyncCallback<Contact>	是	回调函数，返回查询的联系人对象。

示例：

contact.queryContact('xxx', {
    holderId: 0,
    bundleName: "",
    displayName: ""
}, {
    attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
}, (err, data) => {
    if (err) {
        console.log(`queryContact callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log(`queryContact callback: success data->${JSON.stringify(data)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

contact.queryContact

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
key	string	是	联系人的key值，一个联系人对应一个key。
holder	Holder	否	创建联系人的应用信息。
attrs	ContactAttributes	否	联系人的属性列表。

返回值：

类型	说明
Promise<Contact>	以Promise形式返回结果，返回查询到的联系人对象。

示例：

let promise = contact.queryContact('xxx', {
    holderId: 0,
    bundleName: "",
    displayName: ""
}, {
    attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
});
promise.then((data) => {
    console.log(`queryContact success: data->${JSON.stringify(data)}`);
}).catch((err) => {
    console.error(`queryContact fail: err->${JSON.stringify(err)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

contact.queryContacts

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Array<Contact>>	是	回调函数，返回查询到的联系人对象数组。

示例：

contact.queryContacts((err, data) => {
    if (err) {
        console.log(`queryContacts callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log(`queryContacts callback: success data->${JSON.stringify(data)}`);
});1.
2.
3.
4.
5.
6.
7.

contact.queryContacts

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
holder	Holder	是	创建联系人的应用信息。
callback	AsyncCallback<Array<Contact>>	是	回调函数，返回查询到的联系人对象数组。

示例：

contact.queryContacts({
    holderId: 0,
    bundleName: "",
    displayName: ""
}, (err, data) => {
    if (err) {
        console.log(`queryContacts callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log(`queryContacts callback: success data->${JSON.stringify(data)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

contact.queryContacts

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
attrs	ContactAttributes	是	联系人的属性列表。
callback	AsyncCallback<Array<Contact>>	是	回调函数，返回查询到的联系人对象数组。

示例：

contact.queryContacts({
    attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
}, (err, data) => {
    if (err) {
        console.log(`queryContacts callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log(`queryContacts callback: success data->${JSON.stringify(data)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.

contact.queryContacts

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
holder	Holder	是	创建联系人的应用信息。
attrs	ContactAttributes	是	联系人的属性列表。
callback	AsyncCallback<Array<Contact>>	是	回调函数，返回查询到的联系人对象数组。

示例：

contact.queryContacts({
    holderId: 0,
    bundleName: "",
    displayName: ""
}, {
    attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
}, (err, data) => {
    if (err) {
        console.log(`queryContacts callback: err->${JSON.stringify(err)}`);
        return;
    }
    console.log(`queryContacts callback: success data->${JSON.stringify(data)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

contact.queryContacts

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

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

需要权限：ohos.permission.READ_CONTACTS

系统能力：SystemCapability.Applications.ContactsData

参数：

参数名	类型	必填	说明
holder	Holder	否	创建联系人的应用信息。
attrs	ContactAttributes	否	联系人的属性列表。

返回值：

类型	说明
Promise<Array<Contact>>	以Promise形式返回结果，返回查询到的联系人对象数组。

示例：

let promise = contact.queryContacts({
    holderId: 0,
    bundleName: "",
    displayName: ""
}, {
    attributes: [contact.Attribute.ATTR_EMAIL, contact.Attribute.ATTR_NAME]
});
promise.then((data) => {
    console.log(`queryContacts success: data->${JSON.stringify(data)}`);
}).catch((err) => {
    console.error(`queryContacts fail: err->${JSON.stringify(err)}`);
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

文章转载自：https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-contact-0000001478181645-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001478181645__导入模块

分类

卡片开发

三方库

标签

HarmonyOS API

已于2023-4-6 17:42:14修改

51CTO

51CTO博客

51CTO学堂

HarmonyOS API：@ohos.contact (联系人)

@ohos.contact (联系人)

导入模块

contact.addContact

contact.addContact

contact.deleteContact

contact.deleteContact

contact.updateContact

contact.updateContact

contact.updateContact

contact.isLocalContact

contact.isLocalContact

contact.isMyCard

contact.isMyCard

contact.queryMyCard

contact.queryMyCard

contact.queryMyCard

contact.selectContact

contact.selectContact

contact.queryContact

contact.queryContact

contact.queryContact

contact.queryContact

contact.queryContact

contact.queryContacts

contact.queryContacts

contact.queryContacts

contact.queryContacts

contact.queryContacts

目录

订阅鸿蒙技术特刊，精选内容抢先看