# graphemer 中文文档

规范地址：https://npmcn.com/package/graphemer/

版本：1\.4\.0
npm 元数据更新时间：2023-06-22T16:32:15.232Z
中文译文更新时间：2026-11-05T16:44:27.420Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/graphemer
原文对照：https://npmcn.com/package/graphemer/?lang=original
项目主页：https://github.com/flmnt/graphemer
源码仓库：https://github.com/flmnt/graphemer

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

- 包体积（解压后）：812 kB，19 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2020-09-14T15:37:51.043Z
- 最新版本发布：2022-09-19T10:19:34.014Z
- 近 30 天下载量：148248300（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 0 个）

## 中文简介

一个 JavaScript 库,将字符串突破到他们个人的用户感知字符(包括emojis!)中

## 安装

```sh
npm install graphemer
```

也可以使用：`pnpm add graphemer`、`yarn add graphemer`、`bun add graphemer`

## README

# 图形解析器: Unicode 字符分拆器

## 导言

这个图书馆继续工作 [图形分割符](https://github.com/orling/grapheme-splitter) 并支持下列 unicode 版本:

-   Unicode 15 及以下编码 `[v1.4.0]`
-   统一码 14 及以下 `[v1.3.0]`
-   Unicode 13 及以下编码 `[v1.1.0]`
-   Unicode 11 及以下编码 `[v1.0.0]` ( Unicode 10 支持 ) `grapheme-splitter`(中文(简体) )

在JavaScript中,字符串字符与用户将单独称为"字母"的关系并不总是一对一的. 一些符号由几个字符代表. 这可能会在分出字符串,无意中将多字符串字母切成一半时出问题,或者在需要字符串中的实际字母数时出问题.

例如,"🌷","🎁","😜"和"👍"等emoji字符分别由两个JavaScript字符代表(高代词和低代词). 也就是说,

```javascript
'🌷'.length == 2;
```

合并的emoji甚至更长:

```javascript
'🏳️‍🌈'.length == 6;
```

更有甚者,一些语言往往包括了合并标记——用来修改之前的字母的字符. 常见的例子有德文字母ü和西班牙字母ñ. 有时,它们既可以作为单一字符,也可以作为字母+组合标记,两种形式同样有效:

```javascript
var two = 'ñ'; // unnormalized two-char n+◌̃, i.e. "\u006E\u0303";
var one = 'ñ'; // normalized single-char, i.e. "\u00F1"

console.log(one != two); // prints 'true'
```

Unicode 正常化,由流行的 punycode.js 库或 ECMAScript 6's String.commonize 执行,可以 **有时** 修复这些差异, 将两个字符序列变成单个字符。 但这是 **没有** 所有情况都够了 有些语言如印地语在字母上广泛使用组合标记,由于可能组合的数量之多,这些字母没有专用的单码点Unicode序列. 例如,印地语"QQ"由5个字母和3个组合标记组成:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

这其实只是5个用户感知到的字母:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

以及Unicode正常化不会适当结合. 也有一些不寻常的字母+组合标记组合,没有专门的Unicode编码点. 字符串 ZQQALQGQQ QQǪ̵̹̻̝̳͂̌̌͘明显有5个独立的字母,但实际上由58个JavaScript字符所组成,其中大部分是合并标记.

输入 `graphemer` 图书馆。 它可以用来将JavaScript字符串适当分解为人类用户会称为"单独的字母"(或Unicode名词中的"扩展的图形集群"),不管其内部代表是什么. 它是一个执行 [默认图形集群边界](http://unicode.org/reports/tr29/#Default_Grapheme_Cluster_Table) 联 合 国 [29号未爆炸弹药](http://www.unicode.org/reports/tr29/)。 。 。 .

## 安装

安装 `graphemer` 使用以下国家预防机制命令:

```
$ npm i graphemer
```

## 使用量

如果你在用的话 [字体](https://www.typescriptlang.org/) 或者编译器喜欢 [宝贝](https://babeljs.io/) (或像Create React App之类的东西)事情相当简单;只是导入,初始化和使用!

```javascript
import Graphemer from 'graphemer';

const splitter = new Graphemer();

// split the string to an array of grapheme clusters (one string each)
const graphemes = splitter.splitGraphemes(string);

// iterate the string to an iterable iterator of grapheme clusters (one string each)
const graphemeIterator = splitter.iterateGraphemes(string);

// or do this if you just need their number
const graphemeCount = splitter.countGraphemes(string);
```

如果你用香草的话 节点你可以使用 `require()` 方法.

```javascript
const Graphemer = require('graphemer').default;

const splitter = new Graphemer();

const graphemes = splitter.splitGraphemes(string);
```

## 实例

```javascript
import Graphemer from 'graphemer';

const splitter = new Graphemer();

// plain latin alphabet - nothing spectacular
splitter.splitGraphemes('abcd'); // returns ["a", "b", "c", "d"]

// two-char emojis and six-char combined emoji
splitter.splitGraphemes('🌷🎁💩😜👍🏳️‍🌈'); // returns ["🌷","🎁","💩","😜","👍","🏳️‍🌈"]

// diacritics as combining marks, 10 JavaScript chars
splitter.splitGraphemes('Ĺo͂řȩm̅'); // returns ["Ĺ","o͂","ř","ȩ","m̅"]

// individual Korean characters (Jamo), 4 JavaScript chars
splitter.splitGraphemes('뎌쉐'); // returns ["뎌","쉐"]

// Hindi text with combining marks, 8 JavaScript chars
splitter.splitGraphemes('अनुच्छेद'); // returns ["अ","नु","च्","छे","द"]

// demonic multiple combining marks, 75 JavaScript chars
splitter.splitGraphemes('Z͑ͫ̓ͪ̂ͫ̽͏̴̙̤̞͉͚̯̞̠͍A̴̵̜̰͔ͫ͗͢L̠ͨͧͩ͘G̴̻͈͍͔̹̑͗̎̅͛́Ǫ̵̹̻̝̳͂̌̌͘!͖̬̰̙̗̿̋ͥͥ̂ͣ̐́́͜͞'); // returns ["Z͑ͫ̓ͪ̂ͫ̽͏̴̙̤̞͉͚̯̞̠͍","A̴̵̜̰͔ͫ͗͢","L̠ͨͧͩ͘","G̴̻͈͍͔̹̑͗̎̅͛́","Ǫ̵̹̻̝̳͂̌̌͘","!͖̬̰̙̗̿̋ͥͥ̂ͣ̐́́͜͞"]
```

## 类型脚本

Graphemer是用 TypeScript 构建的,当然还包括类型声明.

```javascript
import Graphemer from 'graphemer';

const splitter = new Graphemer();

const split: string[] = splitter.splitGraphemes('Z͑ͫ̓ͪ̂ͫ̽͏̴̙̤̞͉͚̯̞̠͍A̴̵̜̰͔ͫ͗͢L̠ͨͧͩ͘G̴̻͈͍͔̹̑͗̎̅͛́Ǫ̵̹̻̝̳͂̌̌͘!͖̬̰̙̗̿̋ͥͥ̂ͣ̐́́͜͞');
```

## 捐款

见 [贡献指南](https://npmcn.com/package/graphemer/CONTRIBUTING.md)。 。 。 .

## 鸣谢

这个图书馆是Orlin Georgiev和Huáng Jünliàng在Orlin Georgiev和Huáng Jünliàng at at [https://github.com/orling/grapheme-splitter 互联网档案馆的存檔,存档日期2013-12-02](https://github.com/orling/grapheme-splitter)。 。 。 .

原图书馆深受德文·高维特优秀作品的影响 [断取相图](https://github.com/devongovett/grapheme-breaker) CoffeeScript 库.

## 常见问题

### graphemer 是什么？

一个 JavaScript 库,将字符串突破到他们个人的用户感知字符\(包括emojis\!\)中

### 如何安装 graphemer？

在项目目录运行 npm install graphemer，或使用 pnpm add / yarn add / bun add。

### graphemer 支持 TypeScript 吗？

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

### graphemer 支持 ESM 还是 CommonJS？

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

### graphemer 可以商用吗？

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

### graphemer 的下载量有多少？

根据 npm 官方下载统计，graphemer 在 2026/10/05 – 2026/11/03 这 30 天内被下载 148,248,300 次，日均约 4,941,610 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### graphemer 还在维护吗？

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