VCard是电子名片的文件格式标准。它一般附加在电子邮件之后,但也可以用于其它场合(如在网际网路上相互交换)。
当前访问频次受限,请登录后继续访问
VCard
简介
VCard是电子名片的文件格式标准。它一般附加在电子邮件之后,但也可以用于其它场合(如在网际网路上相互交换)。 VCard可包含的信息有:姓名、地址资讯、电话号码、URL,logo,相片等。本库支持VCard标准2.0和3.0。

下载安装
ohpm install @ohos/vcard
OpenHarmony ohpm 环境配置等更多内容,请参考 如何安装OpenHarmony HAR。
使用说明
生成VCard
import {contact,VCardBuilder,VCardConfig} from "@ohos/vcard";
let myCard= new contact.Contact();
let nickName = new contact.NickName();
nickName.nickName ="wangermazi";
myCard.nickName = nickName;
let eMail = new contact.Email();
eMail.labelName = "labelName";
eMail.labelId = 2;
eMail.email = "zhangsan@universe.com";
myCard.emails = [eMail];
let builder = new VCardBuilder(VCardConfig.VCARD_TYPE_V21_GENERIC,"UTF-8");
builder.appendNickNames(myCard);
builder.appendEmails(myCard);
let result = builder.toString();
解析VCard文本
VCard 解析支持两种方式:文件方式解析和内容方式解析。
示例1:解析VCard文件
import fs from '@ohos.file.fs';
import {VCardParserImpl_V21, VCardEntry, VCardInterpreter, VCardProperty} from "@ohos/vcard";
let vCardEntry = new VCardEntry();
class MyVCardInterpreter implements VCardInterpreter{
onVCardStarted(): void {
}
onVCardEnded(): void {
}
onEntryStarted(): void {
}
onEntryEnded(): void {
}
onPropertyCreated(property: VCardProperty): void {
vCardEntry.addProperty(property);
}
}
let myParser = new VCardParserImpl_V21();
myParser.addInterpreter(new MyVCardInterpreter());
let fileDescriptor = fs.openSync("./pathTo/00002.vcf", 0o100|0o2);
myParser.parse(fileDescriptor.fd);
vCardEntry.consolidateFields();
let nickName = vCardEntry.getNickNameList();
let emails= vCardEntry.getEmailList();
示例2:解析VCard内容
import {VCardParserImpl_V21,VCardEntry,VCardInterpreter,VCardProperty} from "@ohos/vcard";
const vcardContent = `BEGIN:VCARD
VERSION:2.1
N:张;三;;;
FN:张三
X-PHONETIC-FIRST-NAME:zhangsan
NICKNAME:wangermazi
TEL;TYPE=CELL:135792468102
EMAIL;TYPE=WORK:zhangsan@universe.com
END:VCARD`;
let vCardEntry = new VCardEntry()
class MyVCardInterpreter implements VCardInterpreter{
onVCardStarted(): void {
}
onVCardEnded(): void {
}
onEntryStarted(): void {
}
onEntryEnded(): void {
}
onPropertyCreated(property: VCardProperty): void {
vCardEntry.addProperty(property)
}
}
let myParser = new VCardParserImpl_V21();
myParser.addInterpreter(new MyVCardInterpreter());
myParser.parseVCardText(vcardContent);
vCardEntry.consolidateFields();
let nickName = vCardEntry.getNickNameList();
let emails= vCardEntry.getEmailList();
接口说明
接口
模块总览
| 模块 | 描述 |
|---|---|
| StringBuilder | 字符串构造类。 |
| VCardBuilder | VCard 构造器。 |
| VCardParserImpl_V21 | 解析器具体实现类。 |
| HOSBase64 | Base64 编解码工具类。 |
| Utf8ArrayToStr | Uint8Array转字符串方法。 |
| VCardInterpreter | 解析事件的回调接口/处理器。 |
| VCardProperty | vCard 中的单个属性。 |
| VCardConfig | 解析器配置管理器。 |
| contact | 联系人对象模型。 |
| VCardEntry | VCard对象,存储联系人信息。 |
| TextUtils | 文本处理工具类。 |
| GlobalContext | 全局对象,解析字符串为整数函数。 |
1.StringBuilder
let stringBuilder = new StringBuilder();
| 方法 | 参数 | 描述 |
|---|---|---|
| append | content: string | 添加字符串内容。 |
| getUint8Bytes | / | 获取Uint8Array格式的内容。 |
| clear | / | 清空内容。 |
| size | / | 获取数组长度。 |
| toString | / | 转换为string。 |
2.VCardBuilder
let builder=new VCardBuilder(VCardConfig.VCARD_TYPE_V21_GENERIC,"UTF-8");
| 方法 | 参数 | 描述 |
|---|---|---|
| appendNickNames | iContact: Contact | 昵称。 |
| appendNameProperties | iContact: Contact | 名字。 |
| appendPhones | iContact: Contact | 电话。 |
| appendEmails | iContact: Contact | 电子邮件。 |
| appendPostals | iContact: Contact | 地址。 |
| appendIms | iContact: Contact | 社交工具。 |
| appendWebsites | iContact: Contact | 网站地址。 |
| appendOrganizations | iContact: Contact | 组织。 |
| appendPhotos | iContact: Contact | 照片地址。 |
| appendNotes | iContact: Contact | 备注。 |
| appendGroupMemberShip | iContact: Contact | 群组。 |
| appendEvents | iContact: Contact | 事件。 |
| appendRelation | iContact: Contact | 关系。 |
| appendPostalLine | type: number, label: string, contentValues: contact.PostalAddress , isPrimary: boolean, emitEveryTime: boolean |
单个地址。 |
| appendEmailLine | type: number, label: string, rawValue: string, isPrimary: boolean |
单个电子邮件。 |
| appendTelLine | typeAsInteger: number , label: string, encodedValue: string, isPrimary: boolean |
单个电话。 |
| appendPhotoLine | encodedValue: string, photoType: string | 单个照片地址。 |
| appendSpecificProperty | mimeType: string, typeModel: contact.NickName/contact.Event/contact.Relation |
追加特定类型的属性。 |
| appendLineWithCharsetAndQPDetection PropertyNameAndRawVAlue |
propertyName: string, rawValueList: Array |
追加自动检测字符集和QP编码的方法。 |
| appendLineWithCharsetAndQPDetection PropNameParamListRawValue |
propertyName: string, parameterList: Array, rawValue: string |
带参数列表的字符集和QP检测追加方法。 |
| appendLineWithCharsetAndQPDetection | propertyName: string, parameterList: Array, rawValueList: Array |
通用的字符集和QP检测追加方法。 |
| appendLineWithPropertyNameAndRawValue | propertyName: string, rawValue: string |
追加属性名和原始值。 |
| appendLineWithProptynameAndRawValueList | propertyName: string, rawValueList: Array |
追加属性名和多个原始值。 |
| appendLineWithPropertyNameAndRawValue AndCharsetAndQuotePrintable |
propertyName: string, rawValue: string, needCharset: boolean, reallyUseQuotedPrintable: boolean |
追加带字符集和引用可打印编码的属性。 |
| appendLineWithPropertyNameAndParamter ListAndRawValue |
propertyName: string, parameterList: Array, rawValue: string |
追加属性名、参数列表和原始值。 |
| appendLineWithPropertyName | propertyName: string, parameterList: Array, rawValue: string, needCharset: boolean, reallyUseQuotedPrintable: boolean |
使用属性名追加一行,需要单独设置值。 |
| appendLineWithoutParamterList | propertyName: string, rawValueList: Array, needCharset: boolean, needQuotedPrintable: boolean |
追加属性名和多个原始值。 |
| appendLine | propertyName: string, parameterList: Array = null, rawValueList: Array, needCharset: boolean, needQuotedPrintable: boolean |
追加一行内容。 |
| toString | / | 将 vCard 对象转换为字符串表示形式。 |
3.VCardParserImpl_V21
let introduction = new VCardParserImpl_V21();
| 方法 | 参数 | 描述 |
|---|---|---|
| addInterpreter | interpreter: VCardInterpreter | 解析事件的回调接口。 |
| parse | is: string/number | 解析VCard文本,入参为文件描述符。 |
| parseVCardText | vCardText: InputStream | 解析VCard文本,入参为Vcard字符串。 |
| parseOne | is: string /number | 解析VCard文本,入参为文件描述符(解析第一个VCard文本内容)。 |
| cancel | / | 取消。 |
4.HOSBase64
let hosBase64 = new HOSBase64();
| 方法 | 参数 | 描述 |
|---|---|---|
| encode | str: string | base64编码。 |
| decode | str: string | base64解码。 |
5.Utf8ArrayToStr
Uint8Array转字符串方法:Utf8ArrayToStr(array: Uint8Array, encoding: string = "utf8");
6.VCardInterpreter
| 方法 | 参数 | 描述 |
|---|---|---|
| onVCardStarted | / | vCard解析开始时调用。 |
| onVCardEnded | / | vCard解析完成后调用。 |
| onEntryStarted | / | 当开始解析一个 vCard 条目时调用。 |
| onEntryEnded | / | 当解析完一个 vCard 条目后调用。 |
| onPropertyCreated | property: VCardProperty | 在创建属性时调用。 |
7.VCardProperty
| 方法 | 参数 | 描述 |
|---|---|---|
| getParamMapString | / | 获取参数字符串。 |
| toString | / | 转换为string。 |
| setName | name: string | 设置属性名字。 |
| addGroup | group: string | 添加群组。 |
| setParameter | paramName: string, paramValue: string | 设置参数。 |
| addParameter | paramName: string, paramValue: string | 添加参数。 |
| setRawValue | rawValue: string | 设置属性原始值。 |
| setValues | ...propertyValues: string[] | 设置属性值列表。 |
| addValues | ...propertyValues: string[] | 添加属性值列表项。 |
| setByteValue | byteValue: Uint8Array | 设置二进制值。 |
| getName | / | 获取属性名字。 |
| getGroupList | / | 获取群组列表。 |
| getParameterMap | / | 获取参数映射对象。 |
| getParameters | type: string | 获取指定参数。 |
| getRawValue | / | 获取属性原始值。 |
| getValueList | / | 获取属性值列表。 |
| getByteValue | / | 获取二进制值。 |
8.VCardConfig
属性
| 名称 | 类型 | 描述 |
|---|---|---|
| DEFAULT_INTERMEDIATE_CHARSET | string | 中间转换时默认字符集,确保编码一致(UTF-8)。 |
| DEFAULT_IMPORT_CHARSET | string | 导入 vCard 文本时默认字符集。 |
| DEFAULT_EXPORT_CHARSET | string | 导出 vCard 文本时默认字符集。 |
| VERSION_21 | number | vCard 2.1 版本的位标识。 |
| VERSION_MASK | number | 用于从配置值中提取版本位。 |
| NAME_ORDER_DEFAULT | number | 默认姓名顺序(常见的名在前、姓在后或平台默认策略)。 |
| NAME_ORDER_EUROPE | number | 欧洲常用的姓在前顺序的位标识。 |
| NAME_ORDER_JAPANESE | number | 日式姓名顺序(姓在前、名在后)的位标识。 |
| NAME_ORDER_MASK | number | 提取姓名顺序位的掩码。 |
| FLAG_USE_PROPERTY | number | 允许使用一组特定属性的标志位。 |
| FLAG_USE_DEFACT_PROPERTY | number | 启用常见但非标准属性(defact)的标志位。 |
| FLAG_DOCOMO | number | 标识是否带有 DoCoMo 设备特性。 |
| FLAG_REFRAIN_QP_TO_NAME_PROPERTIES | number | 禁止对姓名属性使用 quoted-printable。 |
| FLAG_CONVERT_PHONETIC_NAME_STRINGS | number | 需要转换假名/拼音字段的标志位。 |
| FLAG_APPEND_TYPE_PARAM | number | 需要在字段后附带 TYPE= 参数时启用。 |
| FLAG_REFRAIN_PHONE_NUMBER_FORMATTING | number | 禁用电话号码格式化。 |
| FLAG_REFRAIN_IMAGE_EXPORT | number | 导出时跳过照片。 |
| FLAG_REFRAIN_EVENTS_EXPORT | number | 导出时跳过事件信息。 |
| FLAG_REFRAIN_ADDRESS_EXPORT | number | 导出时跳过地址信息。 |
| FLAG_REFRAIN_EMAIL_EXPORT | number | 导出时跳过邮箱信息。 |
| FLAG_REFRAIN_ORGANIZATION_EXPORT | number | 导出时跳过单位信息。 |
| FLAG_REFRAIN_NOTES_EXPORT | number | 导出时跳过备注。 |
| FLAG_REFRAIN_PHONETIC_NAME_EXPORT | number | 导出时跳过读音字段。 |
| FLAG_REFRAIN_WEBSITES_EXPORT | number | 导出时跳过网址。 |
| FLAG_REFRAIN_NICKNAME_EXPORT | number | 导出时跳过昵称。 |
| VCARD_TYPE_UNKNOWN | number | 占位的未知类型。 |
| VCARD_TYPE_V21_GENERIC | number | vCard 2.1 通用配置组合(默认顺序 + 常见属性)。 |
| VCARD_TYPE_V21_GENERIC_STR | string | 对应字符串标识 v21_generic。 |
| VCARD_TYPE_V21_EUROPE | number | 2.1 版本、欧洲姓名顺序的组合配置。 |
| VCARD_TYPE_V21_EUROPE_STR | string | 字符串标识 v21_europe。 |
| VCARD_TYPE_V21_JAPANESE | number | 2.1 版本、日式顺序配置。 |
| VCARD_TYPE_V21_JAPANESE_STR | string | 字符串标识 v21_japanese_utf8。 |
| VCARD_TYPE_V21_JAPANESE_MOBILE | number | 2.1 版本、日系手机额外需求(转换假名+限制 QP)。 |
| VCARD_TYPE_V21_JAPANESE_MOBILE_STR | string | 字符串标识 v21_japanese_mobile。 |
| VCARD_TYPE_DOCOMO | number | 基于日式手机配置,附带 DoCoMo 特性。 |
| VCARD_TYPE_DOCOMO_STR | string | 字符串标识 docomo。 |
| VCARD_TYPE_DEFAULT | number | 默认类型,等同 VCARD_TYPE_V21_GENERIC。 |
| sVCardTypeMap | Map<string, number> | 字符串标识到具体类型配置的映射表。 |
| sJapaneseMobileTypeSet | Set | 日系移动设备类型集合,用于快速判断。 |
方法
| 方法 | 返回值 | 描述 |
|---|---|---|
| getVCardTypeFromString(vcardTypeString: string) | number | 将字符串(大小写无关)映射为预设类型,失败回退默认。 |
| isVersion21(vcardType: number) | boolean | 判断配置是否为 vCard 2.1。 |
| shouldUseQuotedPrintable(vcardType: number) | boolean | 除 v3.0 以外默认使用 quoted-printable。 |
| getNameOrderType(vcardType: number) | number | 读取姓名顺序位,决定姓/名展示顺序。 |
| usesSpecificProperty(vcardType: number) | boolean | 是否启用 FLAG_USE_PROPERTY 定义的属性集。 |
| usesDefactProperty(vcardType: number) | boolean | 是否启用 FLAG_USE_DEFACT_PROPERTY。 |
| shouldRefrainQPToNameProperties(vcardType: number) | boolean | 当 v3.0 或设置了禁止标志时,不对姓名字段使用 QP。 |
| appendTypeParamName(vcardType: number) | boolean | v3.0 或显式标志下需要在属性后追加 TYPE 参数。 |
| isJapaneseDevice(vcardType: number) | boolean | 利用 sJapaneseMobileTypeSet 判断是否为日系设备配置。 |
| refrainPhoneNumberFormatting(vcardType: number) | boolean | 是否跳过电话号码格式化。 |
| needsToConvertPhoneticString(vcardType: number) | boolean | 是否需要转换假名/拼音字符串。 |
| onlyOneNoteFieldIsAvailable(vcardType: number) | boolean | Docomo 配置下仅允许一个备注字段。 |
| isDoCoMo(vcardType: number) | boolean | 是否包含 FLAG_DOCOMO 标志。 |
9.VCardEntry
let vCardEntry = new VCardEntry(vcardType?: number);
| 方法 | 参数 | 描述 |
|---|---|---|
| addProperty | property: VCardProperty | 添加property。 |
| consolidateFields | / | 联系人数据的合并与去重处理。 |
| getNameData | / | 获取名字信息。 |
| getNickNameList | / | 获取昵称列表。 |
| getBirthday | / | 获取生日信息。 |
| getNotes | / | 获取备注信息。 |
| getPhoneList | / | 获取电话信息。 |
| getEmailList | / | 获取电子邮件列表。 |
| getPostalList | / | 获取地址信息。 |
| getOrganizationList | / | 获取组织。 |
| getImList | / | 获取社交工具。 |
| getPhotoList | / | 获取照片地址。 |
| getWebsiteList | / | 获取网站地址。 |
| getDisplayName | / | 获取显示名称。 |
| getUnknownXData | / | 获取未知扩展数据。 |
| getCustomData | / | 获取自定义信息。 |
| getAnniversary | / | 获取纪念日。 |
| getGroup | / | 获取所属群组。 |
10.TextUtils
| 方法 | 参数 | 描述 |
|---|---|---|
| isEmpty | params?: string | 检查字符串是否为空。 |
| equals | a: string, b: string | 严格比较两个字符串是否完全相等。 |
| isSurrogate | ch: number | 检查一个 Unicode 码点是否属于代理区。 |
| isHighSurrogate | ch: number | 检查一个 Unicode 码点是否是高代理。 |
| isLowSurrogate | ch: number | 检查一个 Unicode 码点是否是低代理。 |
| offsetByCodePointsAImpl | seq: string, index: number, codePointOffset: number | 根据给定的 Unicode 码点偏移量,计算字符串中的新索引位置。 |
| offsetByCodePoints | seq: string, index: number,codePointOffset: number | 根据给定的 Unicode 码点偏移量,在字符串中安全地移动索引位置。 |
11.GlobalContext
| 方法 | 参数 | 描述 |
|---|---|---|
| parseInt | str, radix?: number | 解析字符串为整数。 |
12.contact
let Utf8ArrayToStr = new Utf8ArrayToStr(array: Uint8Array);
| 方法 | 参数 | 描述 |
|---|---|---|
| emails | Email[] | 邮件。 |
| events | Event[] | 事件。 |
| groups | Group[] | 群组。 |
| imAddresses | ImAddress[] | 即时通讯地址。 |
| phoneNumbers | PhoneNumber[] | 电话。 |
| portrait | Portrait | 头像。 |
| postalAddresses | PostalAddress[] | 地址。 |
| relations | Relation[] | 关系。 |
| sipAddresses | SipAddress[] | SIP地址。 |
| websites | Website[] | 网站地址。 |
| name | Name | 名字。 |
| nickName | NickName | 昵称。 |
| note | Note | 备注。 |
| organization | Organization | 组织。 |
类型
| 属性 | 类型 | 说明 |
|---|---|---|
| string | 电子邮件 | |
| labelName | string/null | 标签名称 |
| displayName | string/null | 显示名称 |
| labelId | number | ID |
Event
| 属性 | 类型 | 说明 |
|---|---|---|
| eventDate | ESObject | 事件日期 |
| labelName | string/null | 标签名称 |
| labelId | ESObject | ID |
Group
| 属性 | 类型 | 说明 |
|---|---|---|
| groupId | number/null | 群组ID |
| title | string/null | 标题 |
ImAddress
| 属性 | 类型 | 说明 |
|---|---|---|
| imAddress | ESObject | 即时通讯地址 |
| labelName | string/null | 标签名称 |
| labelId | ESObject | ID |
PhoneNumber
| 属性 | 类型 | 说明 |
|---|---|---|
| labelName | string/null | 标签名称 |
| phoneNumber | string/null | 电话号码 |
| labelId | ESObject | ID |
Portrait
| 属性 | 类型 | 说明 |
|---|---|---|
| uri | string/null | 头像地址 |
PostalAddress
| 属性 | 类型 | 说明 |
|---|---|---|
| city | string/null | 城市 |
| country | string/null | 国家 |
| labelName | string/null | 标签名称 |
| neighborhood | string/null | 社区 |
| pobox | string/null | 邮政信箱 |
| postalAddress | string/null | 邮政地址 |
| postcode | string/null | 邮政编码 |
| region | ESObject | 地区 |
| street | string/null | 街道 |
| labelId | ESObject | ID |
Relation
| 属性 | 类型 | 说明 |
|---|---|---|
| labelName | string/null | 标签名称 |
| relationName | ESObject | 关系名称 |
| labelId | ESObject | ID |
SipAddress
| 属性 | 类型 | 说明 |
|---|---|---|
| labelName | string/null | 标签名称 |
| sipAddress | string/null | sip地址 |
| labelId | number/null | ID |
Website
| 属性 | 类型 | 说明 |
|---|---|---|
| website | ESObject | 网站地址 |
Name
| 属性 | 类型 | 说明 |
|---|---|---|
| familyName | string/null | 姓氏 |
| familyNamePhonetic | string/null | 姓氏音标 |
| fullName | string/null | 全名 |
| givenName | string/null | 名字 |
| givenNamePhonetic | string/null | 名字音标 |
| middleName | string/null | 中间名 |
| middleNamePhonetic | string/null | 中间名音标 |
| namePrefix | string/null | 名字前缀 |
| nameSuffix | string/null | 名字后缀 |
NickName
| 属性 | 类型 | 说明 |
|---|---|---|
| nickName | ESObject | 昵称 |
Note
| 属性 | 类型 | 说明 |
|---|---|---|
| noteContent | ESObject | 备注内容 |
Organization
| 属性 | 类型 | 说明 |
|---|---|---|
| name | ESObject | 所属组织的名称 |
| title | ESObject | 标题 |
关于混淆
- 代码混淆,请查看代码混淆简介。
- 如果希望vcard库在代码混淆过程中不会被混淆,需要在混淆规则配置文件obfuscation-rules.txt中添加相应的排除规则:
-keep
./oh_modules/@ohos/vcard
约束与限制
在下述版本验证通过:
- OpenHarmony API 版本 >=15。
目录结构
|---- VCard
| |---- entry # 示例代码文件夹
| |---- library # vcard库文件夹
| |---- index.ets # 对外接口
| |---- README.MD # 安装使用方法
贡献代码
使用过程中发现任何问题都可以提 Issue 给组件,当然,也非常欢迎发 PR 共建。
开源协议
本项目基于 Apache License 2.0 协议,请自由地享受和参与开源。