# @covve/easy-vcard 中文文档

规范地址：https://npmcn.com/package/%40covve/easy-vcard/

版本：2\.1\.1
npm 元数据更新时间：2026-05-12T19:03:39.332Z
中文译文更新时间：2026-11-10T21:12:13.608Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40covve/easy-vcard
原文对照：https://npmcn.com/package/%40covve/easy-vcard/?lang=original
项目主页：https://github.com/Covve/easy-vcard#readme
源码仓库：https://github.com/Covve/easy-vcard

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：55.2 kB，16 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2019-01-09T12:12:39.290Z
- 最新版本发布：2026-05-12T19:03:39.086Z
- 近 30 天下载量：12487（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 1 个）

## 中文简介

简单的 vcard 缓存

## 安装

```sh
npm install @covve/easy-vcard
```

也可以使用：`pnpm add @covve/easy-vcard`、`yarn add @covve/easy-vcard`、`bun add @covve/easy-vcard`

## README

# 易读卡

### vCards,深思熟虑地做了.

小型类型脚本构建器 [密码4.0](https://tools.ietf.org/html/rfc6350) 字符串 – 流畅, RFC 正确, 0 运行时间依赖性 。 从团队在 [**科维**](https://covve.com/)。 。 。 .

[![npm version](https://img.shields.io/npm/v/@covve/easy-vcard.svg?style=flat-square&labelColor=0F0F0F&color=D9FB51)](https://www.npmjs.com/package/@covve/easy-vcard) [![npm downloads](https://img.shields.io/npm/dm/@covve/easy-vcard.svg?style=flat-square&labelColor=0F0F0F&color=D9FB51)](https://www.npmjs.com/package/@covve/easy-vcard) [![types: TypeScript](https://img.shields.io/npm/types/@covve/easy-vcard.svg?style=flat-square&labelColor=0F0F0F&color=D9FB51)](https://www.typescriptlang.org/) [![license: MIT](https://img.shields.io/npm/l/@covve/easy-vcard.svg?style=flat-square&labelColor=0F0F0F&color=D9FB51)](https://npmcn.com/package/%40covve/easy-vcard/LICENCE.txt) [![build](https://img.shields.io/circleci/build/github/Covve/easy-vcard/master.svg?style=flat-square&labelColor=0F0F0F&color=D9FB51)](https://circleci.com/gh/Covve/easy-vcard) [![node](https://img.shields.io/node/v/@covve/easy-vcard.svg?style=flat-square&labelColor=0F0F0F&color=D9FB51)](https://nodejs.org/)

* * *

VCard spec是很小的,但细节被咬——逃生规则,内容行折叠,代码安全UTF-8. `easy-vcard` 帮你处理,所以你把时间花在你的产品上,而不是在 [RFC 6350 (韩语)](https://tools.ietf.org/html/rfc6350)。 。 。 .

-   **流利建业.** `.addEmail(…).addPhone(…).toString()` 说完了.
-   **RFC - 正确从框出.** `,` `;` `\` 而新线逃离了自己。 线以75octets折叠. 多字节字符(CJK,emoji,RTL)从不撕裂.
-   **零运行时间依赖关系.** ~13 kB on npm. ES2020 输出与 `.d.ts`。 。 。 .
-   **需要的时候,会很友好的.** 弃去 `VERSION:3.0` 用一面旗帜.
-   **战斗测试.** 88个测试跨越了逃生边缘的病例,多条线,i18n,以及光谱的尴尬角.

* * *

## 目录

-   [安装](https://npmcn.com/package/%40covve/easy-vcard/#readme-install)
-   [快开始](https://npmcn.com/package/%40covve/easy-vcard/#readme-quick-start)
-   [它为你处理什么](https://npmcn.com/package/%40covve/easy-vcard/#readme-what-it-handles-for-you)
-   [API 参考](https://npmcn.com/package/%40covve/easy-vcard/#readme-api-reference)
-   [尚未支持](https://npmcn.com/package/%40covve/easy-vcard/#readme-not-yet-supported)
-   [释放](https://npmcn.com/package/%40covve/easy-vcard/#readme-releasing)
-   [关于科夫](https://npmcn.com/package/%40covve/easy-vcard/#readme-about-covve)
-   [许可证](https://npmcn.com/package/%40covve/easy-vcard/#readme-license)

## 安装

```bash
npm install @covve/easy-vcard
```

> 需要节点.js **第18条** (使用内置) `structuredClone`) (中文(简体) ).

## 快开始

```ts
import { VCard } from '@covve/easy-vcard';

const vcard = new VCard()
  .setFullName('Johnny D. Doe-Smith')
  .addFirstName('John')
  .addLastName('Doe')
  .addLastName('Smith')
  .addPrefixName('Dr.')
  .addNickname('Jonny')
  .addPhone('+1 1221112', { pref: '1', type: 'home' })
  .addEmail('jdoe@jdoecomp.co')
  .addTitle('Senior Engineer')
  .addOrganization('Jdoecomp co.', ['North Division']);

console.log(vcard.toString());
```

```vcard
BEGIN:VCARD
VERSION:4.0
FN:Johnny D. Doe-Smith
N:Doe,Smith;John;;Dr.;
NICKNAME:Jonny
TEL;PREF=1;TYPE=home:+1 1221112
EMAIL:jdoe@jdoecomp.co
TITLE:Senior Engineer
ORG:Jdoecomp co.;North Division
END:VCARD
```

每个行是 `CRLF`\- 终止了 75octets以上的行会自动折叠 `CRLF` +空间——你不选择加入.

更喜欢平地物体? 这个 `Formatter` 接受一个 `IVCard` 直接 :

```ts
import { Formatter } from '@covve/easy-vcard';

const text = new Formatter().format({
  name: { fullNames: ['Johnny D. Doe-Smith'] },
  emails: [{ value: 'jdoe@jdoecomp.co' }],
});
```

## 它为你处理什么

### 逃跑——RFC 6350 第3.4节

传出生弦. 图书馆逃走了 `\`, (中文(简体) ), `,`, (中文(简体) ), `;`,以及属性值的新行.

```ts
new VCard()
  .setFullName('John')
  .addNotes('Hello, world; with a newline\nbreak')
  .toString();
```

```vcard
NOTE:Hello\, world\; with a newline\nbreak
```

### 线条折叠——RFC 6350§3.2

超过75个 UTF-8 octets 的内容线被拆分 `CRLF` 和单一的领先空间。 文件夹行走代码点,而非字节 – 多字节字符 ()`中`, (中文(简体) ), `🍕`, (中文(简体) ), `שלום`, (中文(简体) ), `Müller`)从不分裂中性格.

### `VERSION:3.0` 倒计时

一些遗产解析器拒绝4.0标题. 一旗翻来:

```ts
vcard.toString(true);                  // emits VERSION:3.0
new Formatter().format(json, true);    // same
```

其余产出仍遵循4.0常规,因此结果可能不完全有效3.0. 只在必要的时候使用.

## API 参考

> **`IParams`** 是可选参数键的对象 : `label`, (中文(简体) ), `language`, (中文(简体) ), `value`, (中文(简体) ), `pref`, (中文(简体) ), `altId`, (中文(简体) ), `pid`, (中文(简体) ), `type`, (中文(简体) ), `mediatype`, (中文(简体) ), `calscale`, (中文(简体) ), `sortAs`, (中文(简体) ), `geo`, (中文(简体) ), `timezone`, (中文(简体) ), `encoding`。并不是每个属性都接受每个参数——见 [RFC (RFC ) (法语)](https://tools.ietf.org/html/rfc6350) 对于矩阵.

### 名称

| 方法 | 它会做什么 |
| --- | --- |
| `setFullName(fullName)` | 设置强制 `FN` 属性。 如果你省略它,一个是建造从 `N` 组件 |
| `addFirstName(firstName)` | 附录 `N` 首字母名称 |
| `addMiddleName(middleName)` | 附录 `N` 中间名 |
| `addLastName(lastName)` | 附录 `N` 姓 |
| `addPrefixName(pre)` | 附录 `N` 荣誉前缀 |
| `addSuffixName(suf)` | 附录 `N` 荣誉后缀 |

### 联系人

| 方法 | 它会做什么 |
| --- | --- |
| `addNickname(nickname, params?)` | 添加一个 `NICKNAME` 条目 |
| `addPhoto(data, params?)` | 添加一个 `PHOTO` 输入. `data` 可能是 URL 或 Base64 数据 URI |
| `addAddress(street, locality, region, postCode, country, params?)` | 添加一个 `ADR` 输入。 每个组件接受 `string | null | undefined` - 无效和未定义的规范化为 `""` |
| `addPhone(number, params?)` | 添加一个 `TEL` 条目 |
| `addEmail(email, params?)` | 添加一个 `EMAIL` 条目 |
| `addUrl(url, params?)` | 添加一个 `URL` 条目 |

```ts
vcard.addAddress('123 Main St.', null, undefined, 'AB-123', 'USA', { type: 'home' });
// → ADR;TYPE=home:;;123 Main St.;;;AB-123;USA
```

### 工作

| 方法 | 它会做什么 |
| --- | --- |
| `addTitle(title, params?)` | 添加一个 `TITLE` 条目 |
| `addRole(role, params?)` | 添加一个 `ROLE` 条目 |
| `addOrganization(organization, organizationUnits?, params?)` | 添加一个 `ORG` 输入. `organizationUnits` 在主名下列出子单位名称 |

### 杂项

| 方法 | 它会做什么 |
| --- | --- |
| `addNotes(notes, params?)` | 添加一个 `NOTE` 条目 |
| `setRevision(rev, params?)` | 设置 `REV` 属性 |
| `setUID(uid, params?)` | 设置 `UID` 属性 |

### 产出

| 方法 | 回返 |
| --- | --- |
| `toString(forceV3 = false)` | 格式化了 vCard 字符串 |
| `toVcard(forceV3 = false)` | 别名 `toString` |
| `toJSON()` | 内部状态的深克隆为平原 `IVCard` 对象 - 传递给 `Formatter.format(…)` 或者随便你怎么说 |

## 尚未支持

以下 vCard 属性尚未执行 。 公关欢迎.

```
SOURCE  KIND  XML  BDAY  ANNIVERSARY  GENDER  IMPP  LANG  TZ  GEO
LOGO  MEMBER  RELATED  CATEGORIES  PRODID  SOUND  CLIENTPIDMAP
KEY  FBURL  CALADRURI  CALURI
```

**分析已存在的 vCard 字符串已超出范围** —— 说 `easy-vcard` 是一个单行道的东西。 用于解析, 到达 [`vcard4`](https://www.npmjs.com/package/vcard4) 或者说 [`vcf`](https://www.npmjs.com/package/vcf)。 。 。 .

## 释放

出版物由 CircleCI 自动发布.

1.  弹出 `version` 内 `package.json` 添加一个 `CHANGELOG.md` 输入公关。 合并到 `master`。 。 。 .
2.  标记合并承诺 `vX.Y.Z` (必须匹配) `package.json`)并推:
    
    ```bash
    git tag v2.3.0 && git push origin v2.3.0
    ```
    
3.  这个 `publish` 任务运行在标签按键上:安装、构建、涂抹、测试、验证标签匹配 `package.json.version`,则 `npm publish --access public` 使用 `NPM_TOKEN` (原始内容存档于2018-09-21). project env var.

仅限严格分解标记( S)`vMAJOR.MINOR.PATCH`)自动推出. 释放前标签 `v2.3.0-beta.1` 别.

## 关于科夫

[**科维**](https://covve.com/) 帮助专业人士将短暂的相遇转变为重要的联系。 我们建造了各种工具 精心培育网络 —— Covve的名片扫描仪 用于捕捉线索 一种扫描API 用于授权其他产品内部的接触摄入 以及一种CRM 后续的,所以你不必这么做.

`easy-vcard` 是所有这些下面的一个小块 开源的 因为vCard处理是每个联络工具应该正确的东西.

|  |  |
| --- | --- |
| 网站 | [cavve.com (英语)](https://covve.com/) |
| 问题与公关 | [github.com/Covve/易碎卡](https://github.com/Covve/easy-vcard) |

## 许可证

[麻省理工学院](https://npmcn.com/package/%40covve/easy-vcard/LICENCE.txt) © [科维](https://covve.com/)

## 常见问题

### @covve/easy-vcard 是什么？

简单的 vcard 缓存

### 如何安装 @covve/easy-vcard？

在项目目录运行 npm install @covve/easy-vcard，或使用 pnpm add / yarn add / bun add。

### @covve/easy-vcard 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @covve/easy-vcard 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @covve/easy-vcard 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @covve/easy-vcard 可以商用吗？

@covve/easy-vcard 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @covve/easy-vcard 的下载量有多少？

根据 npm 官方下载统计，@covve/easy-vcard 在 2026/10/11 – 2026/11/09 这 30 天内被下载 12,487 次，日均约 416 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @covve/easy-vcard 还在维护吗？

最新版本 2\.1\.1 发布于 2026/05/13（5 个月前）；至今共发布 9 个版本，其中过去 12 个月发布了 1 个；首次发布于 2019/01/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。