[xdi8-transcriber 〇改希顶转写器][site]

[![npm 包][npm-badge]][npm] [![GitHub Pages 构建状态][actions-badge]][actions]

〇改[希顶语][xdi8]↔汉字转写工具

- [X] 字表已更新至 240924 版
- [X] 兼容旧版字表
- [X] 自带多音字提示
- [X] 部分常见多音字读音自动推测

[启动转写器→][site]

引流(?)：DGCK81LNN/fairfax_xdpua — Fairfax字体希顶字母PUA编码版

![](https://github.com/DGCK81LNN/xdi8-transcriber/raw/main/images/snapshot.png)

[site]: https://dgck81lnn.github.io/xdi8-transcriber/
[npm]: https://npmjs.org/package/xdi8-transcriber
[npm-badge]: https://img.shields.io/npm/v/xdi8-transcriber?logo=npm
[actions]: https://github.com/DGCK81LNN/xdi8-transcriber/actions/workflows/pages.yml
[actions-badge]: https://img.shields.io/github/actions/workflow/status/DGCK81LNN/xdi8-transcriber/pages.yml?branch=main&logo=github-actions&logoColor=white
[xdi8]: https://wiki.xdi8.top/wiki/%E5%B8%8C%E9%A1%B6%E8%AF%AD

调用方法

Node:

~~~sh
npm install xdi8-transcriber

或

yarn add xdi8-transcriber
~~~

~~~js
const {
HanziToXdi8Transcriber,
Xdi8ToHanziTranscriber,
} = require("xdi8-transcriber")
// 或
import {
HanziToXdi8Transcriber,
Xdi8ToHanziTranscriber,
} from "xdi8-transcriber"

const h2x = new HanziToXdi8Transcriber()
const x2h = new Xdi8ToHanziTranscriber()
// ...
~~~

CDN：

~~~html

~~~

示例（HanziToXdi8Transcriber）

~~~js
console.log(h2x.transcribe("曾侯乙编钟"));
// 输出：
[
[
{
content: [ { h: '曾', x: 'D8H', v: 'D8H' } ],
note: 'céng',
exceptional: false,
legacy: false
},
{
content: [ { h: '曾', x: 'H3H', v: 'H3H' } ],
note: 'zēng',
exceptional: false,
legacy: false
}
],
[
{
content: [ { h: '侯', x: 'hi6', v: 'hi6' } ],
note: '',
exceptional: false,
legacy: false
},
{
content: [ { h: '侯', x: 'Vhi6', v: 'Vhi6', legacy: true } ],
note: '旧拼写',
exceptional: true,
legacy: true
}
],
{ h: '乙', x: '5E', v: '5E' },
{ h: '编', x: 'abi2', v: 'abi2' },
[
{
content: [ { h: '钟', x: '7iTN', v: '7iTN' } ],
note: '“鐘”的简化字打击乐器；计时的器具；指时间或时刻',
exceptional: false,
legacy: false
},
{
content: [ { h: '钟', x: 'Nzu3', v: 'Nzu3' } ],
note: '“鍾”的简化字盛酒的器皿；（情感）集中、专注；姓氏',
exceptional: false,
legacy: false
},
{
content: [ { h: '钟', x: 'Nz3', v: 'Nz3', legacy: true } ],
note: '旧拼写',
exceptional: true,
legacy: true
}
]
]
~~~

示例（Xdi8ToHanziTranscriber）

~~~js
console.log(x2h.transcribe("wo de Huajbia", { alphaFilter: null }));
// 输出：
[
{ h: '我', x: 'wo', v: '我' },
' ',
{ h: '的', x: 'de', v: '的' },
' ',
[
{
content: [ { h: '挚', x: 'Huaj', v: '挚' }, { h: '友', x: 'bia', v: '友' } ],
note: '',
exceptional: false,
legacy: false
},
{
content: [ { h: '支', x: 'Hua', v: '支' }, { h: '发', x: 'jbia', v: '发' } ],
note: 'jbia — “髪”的简化字 fà',
exceptional: false,
legacy: false
},
{
content: [ { h: '支', x: 'Hua', v: '支' }, { h: '髪', x: 'jbia', v: '髪' } ],
note: '',
exceptional: true,
legacy: false
},
{
content: [ { h: '支', x: 'Hua', v: '支' }, { h: '髮', x: 'jbia', v: '髮' } ],
note: '',
exceptional: true,
legacy: false
}
]
]
~~~

$3

~~〇改希顶语字表可能经常需要更新~~^{_2025年以来，〇改希顶语字表已停止更新_}~~，但某些情况下，可能并不适合直接更新 xdi8-transcriber 包。~~您可使用以下方法获取与当前包版本相兼容的最新字表数据：

1. GET https://data.jsdelivr.com/v1/packages/npm/xdi8-transcriber/resolved?specifier=^当前包版本号（不包含前缀 v）

jsDelivr 将返回一段 JSON 数据。取其根对象上的 version 字段，即为最新兼容的版本号。

2. GET https://cdn.jsdelivr.net/npm/xdi8-transcriber@版本号/lib/data.json

即为字表数据 JSON，解析成对象后传递给转写器类的构造函数即可。

API 参考

$3

~~~ts
type TranscribeResult = TranscribeResultSegment[]
type TranscribeResultSegment = string | TranscribedSegment | Alternation[]
~~~

转写器返回的结果为一个数组，其中每个元素可能是：

* 字符串（无法转写的部分，如标点符号）；
* Alternation 数组（多种可选结果）或
* TranscribedSegment（成功转写的汉字-希顶词对）。

要将转写结果转为字符串，其中的 TranscribedSegment 元素取 v的值，Alternation 元素选择其中一种可能结果，取其 content 数组中各 TranscribedSegment 的 v 的总和。

在希顶转汉字时，若不指定 ziSeparator 分隔符，您可以考虑从结果数组中删去所有仅包含一个空格的字符串（" "），以免在输入文本中用空格分隔了希顶词的情况下，汉字之间出现多余的空格。

#### 示例

~~~js
let result = transcriber.transcribe(text)

if (transcriber instanceof AlphaToHanziTranscriber)
result = result.filter(seg => seg !== " ")

const resultString = result.map(seg => {
if (typeof seg === "string") return seg
if (Array.isArray(seg)) return seg[0].content.map(seg => seg.v).join("")
return seg.v
}).join("")
~~~

$3

~~~ts
interface TranscribedSegment {
h: string
x: string
v: string
legacy?: boolean
}
~~~

成功转写的汉字-希顶词对。v 为转写结果，将转写结果以文本形式表示时，只使用 v 的值即可。h 与 x 分别为汉字与其对应的希顶拼写，用于可视化结果中的汉字注音。若该字词使用旧拼写，legacy 为 true。

特殊地，汉字转希顶时，若指定了 ziSeparator 分隔符，则分隔符会以 h、x 都为空字符串、v 为实际分隔符的 TranscribedSegment 表示。

#### 示例

~~~js
console.log(x2hTranscriber.transcribe("FY"));
// 输出：
[ { x: 'FY', h: '玉', v: '玉' } ]
~~~

~~~js
console.log(h2xTranscriber.transcribe("爱情", { ziSeparator: "-" }));
// 输出：
[
{ h: '爱', x: '4YF', v: '4YF' },
{ h: '', x: '', v: '-' },
{ h: '情', x: 'Yq8', v: 'Yq8' }
]
~~~

$3

~~~ts
interface Alternation {
content: TranscribedSegment[]
note?: string
exceptional?: boolean
legacy?: boolean
}
~~~

当一个字词有多种可选的转写结果时，每种结果用一个 Alternation 表示。

#### 成员 content

该结果中的各汉字-希顶词对。

#### 成员 note

该结果的备注。

#### 成员 exceptional

该结果是否为一个“例外结果”。

汉转希时包含多音字的罕见（无法组词）拼写的结果、希转汉中包含汉字的非常用写法的结果，以及下述包含过时的希顶拼写的结果都被认为是“例外结果”。

目前，“例外”拼写在字表数据中体现为对应的 hh（汉转希）或 xh（希转汉）属性为 "-"。

通常，希转汉时可以忽略“例外结果”。汉转希时“例外结果”的定义将来可能改动，目前不建议使用。

#### 成员 legacy

该结果是否包含过时的希顶拼写。

目前，过时拼写在字表数据中体现为 hh 和 xh 属性都为 "-"，同时注释中注明“旧拼写”。

$3

~~~ts
class HanziToXdi8Transcriber extends HanziToAlphaTranscriber
class HanziToAlphaTranscriber implements Transcriber
~~~

汉字转希顶转写器。

HanziToXdi8Transcriber 包装了 HanziToAlphaTranscriber，将构造函数参数 data 的默认值设为了本模块所导出的 data。

#### 构造函数

~~~ts
new HanziToXdi8Transcriber(data?: Data)
new HanziToAlphaTranscriber(data: Data)
~~~

##### 参数 data

字表数据（data）。

#### 方法 transcribe

~~~ts
function transcribe(input: string, options?: {
ziSeparator?: string
}): TranscribeResult
~~~

将汉字转写为希顶，以 TranscribeResult 形式返回。

##### 选项 options.ziSeparator

相邻汉字之间使用的分隔符。默认为空字符串。推荐设置为空格（" "）。

$3

~~~ts
class Xdi8ToHanziTranscriber extends AlphaToHanziTranscriber
class AlphaToHanziTranscriber implements Transcriber
~~~

希顶转汉字转写器。

Xdi8ToHanziTranscriber 包装了 AlphaToHanziTranscriber，将构造函数参数 data 的默认值设为了本模块所导出的 data，并将 transcribe 方法中选项 options.alphaFilter 的默认值设为了 chatToXdPUA。

#### 构造函数

~~~ts
new Xdi8ToHanziTranscriber(data?: Data)
new AlphaToHanziTranscriber(data: Data)
~~~

##### 参数 data

字表数据（data）。

#### 方法 transcribe

~~~ts
function transcribe(input: string, options?: {
ziSeparator?: string
alphaFilter?: (x: string) => string
}): TranscribeResult
~~~

将希顶转写为汉字，以 TranscribeResult 形式返回。

##### 选项 options.ziSeparator

相邻汉字之间的分隔符。设置为空字符串时，转写器会尝试自动分词；不为空时，转写器将不会自动分词，将连续的字母串统统视为单个希顶词，但会在把希顶词转写成汉字后，自动删去字词之间的分隔符。

默认为空字符串。

##### 选项 options.alphaFilter

若指定，当某个字词出现多个可选结果，选项的注释中出现希顶语时，会使用此函数将聊天字母转换为其他表示方法。在包装类 Xdi8ToHanziTranscriber 中默认为 chatToXdPUA，即转换为希顶字母 PUA 编码；如需保持聊天字母输出，设为 null 即可。

$3

~~~ts
const data: Data
~~~

内置字表数据。

$3

~~~ts
interface Data {
dict: DictEntry[]
subst: Record
}
interface DictEntry {
h: string
x: string
n?: string
hh?: string
xh?: "-"
}
~~~

#### 成员 dict

字表的每一行为一个元素。n、hh、xh 只有多音字或一希对多汉的情况下才需要存在。属性含义如下：

* h：汉字

* x：希顶拼写

* n：注释

* hh：汉希提示

多音字或修改过拼写的汉字使用。为该字该拼写的一系列组词，用空格分隔，本字用“~”代替；或为 "-"，表示该字的该拼写无法组词。用于推测多音字的读音。

汉转希时，若一汉字有多个拼写，会按以下顺序排列：

* 组词符合当前语境的拼写；
* 没有汉希提示的拼写；
* 汉希提示中存在组词，但与当前语境不符的拼写；
* 汉希提示为 "-"，但非过时的拼写；
* 过时拼写。

* xh：希汉提示

一希对多汉时使用。此属性为 "-" 时，表示当前行是该汉字的非常用写法。

希转汉时，若一希顶词有多个对应汉字结果，会按照以下顺序排列：

* 其中所有汉字都没有希汉提示的结果；
* 其中至少一个汉字的希汉提示为 "-"，但不包含过时拼写的结果；
* 包含过时拼写的结果。

目前，汉希提示与希汉提示均为 "-" 表示该汉字的该拼写为过时拼写。

#### 成员 subst

指定一系列字符串替换规则。汉字转希顶时，会根据这些规则对文本进行预处理。

在默认数据中指定的是将拆开表示的“纟火”、“糹火”替换为相对应的希顶字母 PUA 编码码位。这样做是因为 HanziToAlphaTranscriber 的设计要求单个汉字只能用单个 Unicode 代码点表示。

~~~json
{
"纟火": "\ue106",
"糹火": "\ue107",
"\u2eb0火": "\ue106",
"\u2eaf火": "\ue107"
}
~~~

$3

~~~ts
function chatToXdPUA(text: string): string
~~~

将聊天字母转换为希顶字母 PUA 编码。暂不支持扩充字母。

$3

~~~ts
function xdPUAToChat(text: string): string
~~~

将希顶字母 PUA 编码转换为聊天字母。暂不支持扩充字母。

$3

~~~ts
interface Transcriber {
transcribe(input: string, ...args: unknown[]): TranscribeResult
}
~~~

具有 transcribe 方法，其接受字符串作为第一个参数、返回 TranscribeResult 的类型。本模块中的各转写器类都实现该接口。

维护

新字表发布时：

1. 将字表保存到 data/希顶字表xxxxx.xlsx，执行 py tools/totsv.py data/希顶字表xxxxx.xlsx 将其转换为 TSV。

2. 执行 ruby tools/sort.rb data/xxxxxx.tsv，统一字表数据的排序（希顶拼写按希顶字母表顺序简单排序，相同的按汉字 Unicode 码位排序）。

3. 在 data 目录中，执行 node ../tools/append.mjs dict.tsv：此过程可能会移除部分条目的汉希提示，程序会输出相应的提示，在下一步中可能需要将其补回到适当位置。

4. 检查 data/dict.tsv 的 git diff，补充缺少的注释、提示（如新增多音字时，填写各读音的释义或对应普通话读音等）。

* 使用 tools/dictgitdiff.sh data/dict.tsv 可省略 diff 中多余的上下文。当标准输出为控制台时，该脚本会自动使用环境中的 python -m pygments 或 rougify 为 diff 添加颜色。

5. 如果在注释中使用了数字表示拼音声调的写法（如 pin1 yin1），执行 ruby tools/pinyin.rb data/dict.tsv data/dict.tsv，将其转换为声调标号。

6. 执行 node tools/xhhint.js，自动补充一些希汉提示（进行此操作前建议先 git add data/dict.tsv 以便检查）。

7. 更新 README 和 site/app.vue 中注明的字表版本以及更新记录。

8. 修改 package/package.json 中的包版本号，执行 npm run build:package 或其他合适的构建指令，为新的版本号创建 Git 标签，发布包更新。

[xdi8-transcriber 〇改希顶转写器][site]

[![npm 包][npm-badge]][npm] [![GitHub Pages 构建状态][actions-badge]][actions]

〇改[希顶语][xdi8]↔汉字转写工具

- [X] 字表已更新至 240924 版
- [X] 兼容旧版字表
- [X] 自带多音字提示
- [X] 部分常见多音字读音自动推测

[启动转写器→][site]

引流(?)：DGCK81LNN/fairfax_xdpua — Fairfax字体希顶字母PUA编码版

![](https://github.com/DGCK81LNN/xdi8-transcriber/raw/main/images/snapshot.png)

调用方法

Node:

~~~sh
npm install xdi8-transcriber

或

yarn add xdi8-transcriber
~~~

~~~js
const {
HanziToXdi8Transcriber,
Xdi8ToHanziTranscriber,
} = require("xdi8-transcriber")
// 或
import {
HanziToXdi8Transcriber,
Xdi8ToHanziTranscriber,
} from "xdi8-transcriber"

const h2x = new HanziToXdi8Transcriber()
const x2h = new Xdi8ToHanziTranscriber()
// ...
~~~

CDN：

~~~html

~~~

示例（HanziToXdi8Transcriber）

示例（Xdi8ToHanziTranscriber）

$3

1. GET https://data.jsdelivr.com/v1/packages/npm/xdi8-transcriber/resolved?specifier=^当前包版本号（不包含前缀 v）

jsDelivr 将返回一段 JSON 数据。取其根对象上的 version 字段，即为最新兼容的版本号。

2. GET https://cdn.jsdelivr.net/npm/xdi8-transcriber@版本号/lib/data.json

即为字表数据 JSON，解析成对象后传递给转写器类的构造函数即可。

API 参考

$3

~~~ts
type TranscribeResult = TranscribeResultSegment[]
type TranscribeResultSegment = string | TranscribedSegment | Alternation[]
~~~

转写器返回的结果为一个数组，其中每个元素可能是：

* 字符串（无法转写的部分，如标点符号）；
* Alternation 数组（多种可选结果）或
* TranscribedSegment（成功转写的汉字-希顶词对）。

#### 示例

~~~js
let result = transcriber.transcribe(text)

if (transcriber instanceof AlphaToHanziTranscriber)
result = result.filter(seg => seg !== " ")

const resultString = result.map(seg => {
if (typeof seg === "string") return seg
if (Array.isArray(seg)) return seg[0].content.map(seg => seg.v).join("")
return seg.v
}).join("")
~~~

$3

~~~ts
interface TranscribedSegment {
h: string
x: string
v: string
legacy?: boolean
}
~~~

特殊地，汉字转希顶时，若指定了 ziSeparator 分隔符，则分隔符会以 h、x 都为空字符串、v 为实际分隔符的 TranscribedSegment 表示。

#### 示例

~~~js
console.log(x2hTranscriber.transcribe("FY"));
// 输出：
[ { x: 'FY', h: '玉', v: '玉' } ]
~~~

~~~js
console.log(h2xTranscriber.transcribe("爱情", { ziSeparator: "-" }));
// 输出：
[
{ h: '爱', x: '4YF', v: '4YF' },
{ h: '', x: '', v: '-' },
{ h: '情', x: 'Yq8', v: 'Yq8' }
]
~~~

$3

~~~ts
interface Alternation {
content: TranscribedSegment[]
note?: string
exceptional?: boolean
legacy?: boolean
}
~~~

当一个字词有多种可选的转写结果时，每种结果用一个 Alternation 表示。

#### 成员 content

该结果中的各汉字-希顶词对。

#### 成员 note

该结果的备注。

#### 成员 exceptional

该结果是否为一个“例外结果”。

目前，“例外”拼写在字表数据中体现为对应的 hh（汉转希）或 xh（希转汉）属性为 "-"。

通常，希转汉时可以忽略“例外结果”。汉转希时“例外结果”的定义将来可能改动，目前不建议使用。

#### 成员 legacy

该结果是否包含过时的希顶拼写。

目前，过时拼写在字表数据中体现为 hh 和 xh 属性都为 "-"，同时注释中注明“旧拼写”。

$3

~~~ts
class HanziToXdi8Transcriber extends HanziToAlphaTranscriber
class HanziToAlphaTranscriber implements Transcriber
~~~

汉字转希顶转写器。

HanziToXdi8Transcriber 包装了 HanziToAlphaTranscriber，将构造函数参数 data 的默认值设为了本模块所导出的 data。

#### 构造函数

~~~ts
new HanziToXdi8Transcriber(data?: Data)
new HanziToAlphaTranscriber(data: Data)
~~~

##### 参数 data

字表数据（data）。

#### 方法 transcribe

~~~ts
function transcribe(input: string, options?: {
ziSeparator?: string
}): TranscribeResult
~~~

将汉字转写为希顶，以 TranscribeResult 形式返回。

##### 选项 options.ziSeparator

相邻汉字之间使用的分隔符。默认为空字符串。推荐设置为空格（" "）。

$3

~~~ts
class Xdi8ToHanziTranscriber extends AlphaToHanziTranscriber
class AlphaToHanziTranscriber implements Transcriber
~~~

希顶转汉字转写器。

#### 构造函数

~~~ts
new Xdi8ToHanziTranscriber(data?: Data)
new AlphaToHanziTranscriber(data: Data)
~~~

##### 参数 data

字表数据（data）。

#### 方法 transcribe

~~~ts
function transcribe(input: string, options?: {
ziSeparator?: string
alphaFilter?: (x: string) => string
}): TranscribeResult
~~~

将希顶转写为汉字，以 TranscribeResult 形式返回。

##### 选项 options.ziSeparator

默认为空字符串。

##### 选项 options.alphaFilter

$3

~~~ts
const data: Data
~~~

内置字表数据。

$3

~~~ts
interface Data {
dict: DictEntry[]
subst: Record
}
interface DictEntry {
h: string
x: string
n?: string
hh?: string
xh?: "-"
}
~~~

#### 成员 dict

字表的每一行为一个元素。n、hh、xh 只有多音字或一希对多汉的情况下才需要存在。属性含义如下：

* h：汉字

* x：希顶拼写

* n：注释

* hh：汉希提示

汉转希时，若一汉字有多个拼写，会按以下顺序排列：

* xh：希汉提示

一希对多汉时使用。此属性为 "-" 时，表示当前行是该汉字的非常用写法。

希转汉时，若一希顶词有多个对应汉字结果，会按照以下顺序排列：

* 其中所有汉字都没有希汉提示的结果；
* 其中至少一个汉字的希汉提示为 "-"，但不包含过时拼写的结果；
* 包含过时拼写的结果。

目前，汉希提示与希汉提示均为 "-" 表示该汉字的该拼写为过时拼写。

#### 成员 subst

指定一系列字符串替换规则。汉字转希顶时，会根据这些规则对文本进行预处理。

~~~json
{
"纟火": "\ue106",
"糹火": "\ue107",
"\u2eb0火": "\ue106",
"\u2eaf火": "\ue107"
}
~~~

$3

~~~ts
function chatToXdPUA(text: string): string
~~~

将聊天字母转换为希顶字母 PUA 编码。暂不支持扩充字母。

$3

~~~ts
function xdPUAToChat(text: string): string
~~~

将希顶字母 PUA 编码转换为聊天字母。暂不支持扩充字母。

$3

~~~ts
interface Transcriber {
transcribe(input: string, ...args: unknown[]): TranscribeResult
}
~~~

具有 transcribe 方法，其接受字符串作为第一个参数、返回 TranscribeResult 的类型。本模块中的各转写器类都实现该接口。

维护

新字表发布时：

1. 将字表保存到 data/希顶字表xxxxx.xlsx，执行 py tools/totsv.py data/希顶字表xxxxx.xlsx 将其转换为 TSV。

2. 执行 ruby tools/sort.rb data/xxxxxx.tsv，统一字表数据的排序（希顶拼写按希顶字母表顺序简单排序，相同的按汉字 Unicode 码位排序）。

4. 检查 data/dict.tsv 的 git diff，补充缺少的注释、提示（如新增多音字时，填写各读音的释义或对应普通话读音等）。

5. 如果在注释中使用了数字表示拼音声调的写法（如 pin1 yin1），执行 ruby tools/pinyin.rb data/dict.tsv data/dict.tsv，将其转换为声调标号。

6. 执行 node tools/xhhint.js，自动补充一些希汉提示（进行此操作前建议先 git add data/dict.tsv 以便检查）。

7. 更新 README 和 site/app.vue 中注明的字表版本以及更新记录。

8. 修改 package/package.json 中的包版本号，执行 npm run build:package 或其他合适的构建指令，为新的版本号创建 Git 标签，发布包更新。