VCard:基于 OpenHarmony 的 VCard 解析与生成工具项目

VCard是电子名片的文件格式标准。它一般附加在电子邮件之后,但也可以用于其它场合(如在网际网路上相互交换)。

分支1Tags8

VCard

简介

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

img1.png

下载安装

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 组织。

类型

Email

属性 类型 说明
email 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 协议,请自由地享受和参与开源。

项目介绍

VCard是电子名片的文件格式标准。它一般附加在电子邮件之后,但也可以用于其它场合(如在网际网路上相互交换)。

定制我的领域