From d4d58327e59214e0c6ba35784458891c0a6ed7fa Mon Sep 17 00:00:00 2001
From: DGCK81LNN <54282183+DGCK81LNN@users.noreply.github.com>
Date: Tue, 6 Feb 2024 19:31:39 +0800
Subject: [PATCH] doc: update README.md

---
 package/README.md | 447 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 447 insertions(+)

diff --git a/package/README.md b/package/README.md
index 122eeb7..555365c 100644
--- a/package/README.md
+++ b/package/README.md
@@ -21,3 +21,450 @@
 [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
+<script src="https://cdn.jsdelivr.net/npm/xdi8-transcriber"></script>
+<script>
+const h2x = new xdi8Transcriber.HanziToXdi8Transcriber()
+const x2h = new xdi8Transcriber.Xdi8ToHanziTranscriber()
+// ...
+</script>
+
+<!-- 或 -->
+
+<script type="module">
+import {
+  HanziToXdi8Transcriber,
+  Xdi8ToHanziTranscriber,
+} from "https://cdn.jsdelivr.net/npm/xdi8-transcriber/lib/index.mjs"
+
+const h2x = new HanziToXdi8Transcriber()
+const x2h = new Xdi8ToHanziTranscriber()
+// ...
+</script>
+~~~
+
+<details><summary>示例（<code>HanziToXdi8Transcriber</code>）</summary>
+
+~~~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' } ],
+      note: '旧拼写',
+      exceptional: true,
+      legacy: true
+    }
+  ],
+  { h: '乙', x: '5E', v: '5E' },
+  { h: '编', x: 'abi2', v: 'abi2' },
+  [
+    {
+      content: [ { h: '钟', x: 'Nzu3', v: 'Nzu3' } ],
+      note: '“鐘”的简化字 打击乐器；计时的器具；指时间或时刻',
+      exceptional: false,
+      legacy: false
+    },
+    {
+      content: [ { h: '钟', x: '7iTN', v: '7iTN' } ],
+      note: '“鍾”的简化字 盛酒的器皿；（情感）集中、专注；姓氏',
+      exceptional: false,
+      legacy: false
+    },
+    {
+      content: [ { h: '钟', x: 'Nz3', v: 'Nz3' } ],
+      note: '旧拼写',
+      exceptional: true,
+      legacy: true
+    }
+  ]
+]
+~~~
+
+</details>
+
+<details><summary>示例（<code>Xdi8ToHanziTranscriber</code>）</summary>
+
+~~~js
+console.log(x2h.transcribe("wo de Huajbia", { alphaFilter: null }));
+// 输出：
+[
+  { x: 'wo', h: '我', v: '我' },
+  ' ',
+  { x: 'de', h: '的', v: '的' },
+  ' ',
+  [
+    {
+      content: [ { x: 'Huaj', h: '挚', v: '挚' }, { x: 'bia', h: '友', v: '友' } ],
+      note: '',
+      exceptional: false,
+      legacy: false
+    },
+    {
+      content: [ { x: 'Hua', h: '支', v: '支' }, { x: 'jbia', h: '发', v: '发' } ],
+      note: 'jbia — “髪”的简化字 fà',
+      exceptional: false,
+      legacy: false
+    },
+    {
+      content: [ { x: 'Hua', h: '支', v: '支' }, { x: 'jbia', h: '髪', v: '髪' } ],
+      note: '',
+      exceptional: true,
+      legacy: false
+    },
+    {
+      content: [ { x: 'Hua', h: '支', v: '支' }, { x: 'jbia', h: '髮', v: '髮' } ],
+      note: '',
+      exceptional: true,
+      legacy: false
+    }
+  ]
+]
+~~~
+
+</details>
+
+### 通过 CDN 获取最新的字表
+
+〇改希顶语字表可能经常需要更新，但某些情况下，可能并不适合直接更新 `xdi8-transcriber` 包。您可使用以下方法获取与当前包版本相兼容的最新字表数据：
+
+ 1. <code>GET https://<span></span>data.jsdelivr.com/v1/packages/npm/xdi8-transcriber/resolved?specifier=^<mark>当前包版本号（不包含前缀 v）</mark></code>
+
+    jsDelivr 将返回一段 JSON 数据。取其根对象上的 `version` 字段，即为最新兼容的版本号。
+
+ 2. <code>GET https://<span></span>cdn.jsdelivr.net/npm/xdi8-transcriber@<mark>版本号</mark>/lib/data.json</code>
+
+    即为字表数据 JSON，解析成对象后传递给转写器类的构造函数即可。
+
+`xdi8-transcriber` 目前的主版本号为 0。因此，当 `xdi8-transcriber` 的***次***版本号提升（例如从 `0.2.3` 提升至 `0.3.0`）时，新版本会被认为与旧版本不兼容，此时则必须要将 `xdi8-transcriber` 包本身更新到新版本，才能更新到新的字表。
+
+## API 参考
+
+### 类型定义 `TranscribeResult`
+
+~~~ts
+type TranscribeResult = TranscribeResultSegment[]
+type TranscribeResultSegment = string | TranscribedSegment | Alternation[]
+~~~
+
+转写器返回的结果为一个数组，其中每个元素可能是：
+
+  * 字符串（无法转写的部分，如标点符号）；
+  * [`Alternation`](#结构体-alternation) 数组（多种可选结果）或
+  * [`TranscribedSegment`](#结构体-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("")
+~~~
+
+### 结构体 `TranscribedSegment`
+
+~~~ts
+interface TranscribedSegment {
+  h: string
+  x: string
+  v: string
+}
+~~~
+
+成功转写的汉字-希顶词对。`v` 为转写结果，将转写结果以文本形式表示时，只使用 `v` 的值即可。`h` 与 `x` 分别为汉字与其对应的希顶拼写，用于可视化结果中的汉字注音。
+
+特殊地，汉字转希顶时，若指定了 `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' }
+]
+~~~
+
+### 结构体 `Alternation`
+
+~~~ts
+interface Alternation {
+  content: TranscribedSegment[]
+  note?: string
+  exceptional?: boolean
+  legacy?: boolean
+}
+~~~
+
+当一个字词有多种可选的转写结果时，每种结果用一个 `Alternation` 表示。
+
+#### 成员 `content`
+
+该结果中的各汉字-希顶词对。
+
+#### 成员 `note`
+
+该结果的备注。
+
+#### 成员 `exceptional`
+
+该结果是否为一个“例外结果”。
+
+汉转希时包含多音字的罕见（无法组词）拼写的结果、希转汉中包含汉字的非常用写法的结果，以及下述包含过时的希顶拼写的结果都被认为是“例外结果”。
+
+目前，“例外”拼写在[字表数据](#结构体-data)中体现为对应的 `hh`（汉转希）或 `xh`（希转汉）属性为 `"-"`。
+
+通常，希转汉时可以忽略“例外结果”。汉转希时“例外结果”的定义将来可能改动，目前不建议使用。
+
+#### 成员 `legacy`
+
+该结果是否包含过时的希顶拼写。
+
+目前，过时拼写在[字表数据](#结构体-data)中体现为 `hh` 和 `xh` 属性都为 `"-"`，同时注释中注明“旧拼写”。
+
+### 类 `HanziToXdi8Transcriber`、 `HanziToAlphaTranscriber`
+
+~~~ts
+class HanziToXdi8Transcriber extends HanziToAlphaTranscriber
+class HanziToAlphaTranscriber implements Transcriber
+~~~
+
+汉字转希顶转写器。
+
+`HanziToXdi8Transcriber` 包装了 `HanziToAlphaTranscriber`，将构造函数参数 `data` 的默认值设为了本模块所导出的 [`data`](#常量-data)。
+
+#### 构造函数
+
+~~~ts
+new HanziToXdi8Transcriber(data?: Data)
+new HanziToAlphaTranscriber(data: Data)
+~~~
+
+##### 参数 `data`
+
+字表数据（[`data`](#常量-data)）。
+
+#### 方法 `transcribe`
+
+~~~ts
+function transcribe(input: string, options?: {
+  ziSeparator?: string
+}): TranscribeResult
+~~~
+
+将汉字转写为希顶，以 [`TranscribeResult`](#类型定义-transcriberesult) 形式返回。
+
+##### 选项 `options.ziSeparator`
+
+相邻汉字之间使用的分隔符。默认为空字符串。推荐设置为空格（`" "`）。
+
+### 类 `Xdi8ToHanziTranscriber`、 `AlphaToHanziTranscriber`
+
+~~~ts
+class Xdi8ToHanziTranscriber extends AlphaToHanziTranscriber
+class AlphaToHanziTranscriber implements Transcriber
+~~~
+
+希顶转汉字转写器。
+
+`Xdi8ToHanziTranscriber` 包装了 `AlphaToHanziTranscriber`，将构造函数参数 `data` 的默认值设为了本模块所导出的 [`data`](#常量-data)，并将 `transcribe` 方法中选项 `options.alphaFilter` 的默认值设为了 [`chatToXdPUA`](#函数-chattoxdpua)。
+
+#### 构造函数
+
+~~~ts
+new Xdi8ToHanziTranscriber(data?: Data)
+new AlphaToHanziTranscriber(data: Data)
+~~~
+
+##### 参数 `data`
+
+字表数据（[`data`](#常量-data)）。
+
+#### 方法 `transcribe`
+
+~~~ts
+function transcribe(input: string, options?: {
+  ziSeparator?: string
+  alphaFilter?: (x: string) => string
+}): TranscribeResult
+~~~
+
+将希顶转写为汉字，以 [`TranscribeResult`](#类型定义-transcriberesult) 形式返回。
+
+##### 选项 `options.ziSeparator`
+
+相邻汉字之间的分隔符。设置为空字符串时，转写器会尝试自动分词；不为空时，转写器将***不会***自动分词，将连续的字母串统统视为单个希顶词，但会在把希顶词转写成汉字后，自动删去字词之间的分隔符。
+
+默认为空字符串。
+
+##### 选项 `options.alphaFilter`
+
+若指定，当某个字词出现多个可选结果，选项的注释中出现希顶语时，会使用此函数将聊天字母转换为其他表示方法。在包装类 `Xdi8ToHanziTranscriber` 中默认为 [`chatToXdPUA`](#函数-chattoxdpua)，即转换为希顶字母 PUA 编码；如需保持聊天字母输出，设为 `null` 即可。
+
+### 常量 `data`
+
+~~~ts
+const data: Data
+~~~
+
+内置字表数据。
+
+### 结构体 `Data`
+
+~~~ts
+interface Data {
+  dict: DictEntry[]
+  subst: Record<string, string>
+}
+interface DictEntry {
+  h: string
+  x: string
+  n?: string
+  hh?: string
+  xh?: "-"
+}
+~~~
+
+#### 成员 `dict`
+
+字表的每一行为一个元素。`n`、`hh`、`xh` 只有多音字或一希对多汉的情况下才需要存在。属性含义如下：
+
+  * `h`：汉字
+
+  * `x`：希顶拼写
+
+  * `n`：注释
+
+  * `hh`：汉希提示
+
+    多音字或修改过拼写的汉字使用。为该字该拼写的一系列组词，用空格分隔，本字用“`~`”代替；或为 `"-"`，表示该字的该拼写无法组词。用于推测多音字的读音。
+
+    汉转希时，若一汉字有多个拼写，会按以下顺序排列：
+
+      * 组词符合当前语境的拼写；
+      * 没有汉希提示的拼写；
+      * 汉希提示中存在组词，但与当前语境不符的拼写；
+      * 汉希提示为 `"-"`，但非过时的拼写；
+      * 过时拼写。
+
+  * `xh`：希汉提示
+
+    一希对多汉时使用。此属性为 `"-"` 时，表示当前行是该汉字的非常用写法。
+
+    希转汉时，若一希顶词有多个对应汉字结果，会按照以下顺序排列：
+
+      * 其中所有汉字都没有希汉提示的结果；
+      * 其中至少一个汉字的希汉提示为 `"-"`，但不包含过时拼写的结果；
+      * 包含过时拼写的结果。
+
+目前，汉希提示与希汉提示均为 `"-"` 表示该汉字的该拼写为过时拼写。
+
+#### 成员 `subst`
+
+指定一系列字符串替换规则。汉字转希顶时，会根据这些规则对文本进行预处理。
+
+在默认数据中指定的是将拆开表示的“纟火”、“糹火”替换为相对应的希顶字母 PUA 编码码位。这样做是因为 [`HanziToAlphaTranscriber`](#类-hanzitoxdi8transcriber-hanzitoalphatranscriber) 的设计要求单个汉字只能用单个 Unicode 代码点表示。
+
+~~~json
+{
+  "纟火": "\ue106",
+  "糹火": "\ue107",
+  "\u2eb0火": "\ue106",
+  "\u2eaf火": "\ue107"
+}
+~~~
+
+### 函数 `chatToXdPUA`
+
+~~~ts
+function chatToXdPUA(text: string): string
+~~~
+
+将聊天字母转换为希顶字母 PUA 编码。暂不支持扩充字母。
+
+### 函数 `xdPUAToChat`
+
+~~~ts
+function xdPUAToChat(text: string): string
+~~~
+
+将希顶字母 PUA 编码转换为聊天字母。暂不支持扩充字母。
+
+### 接口 `Transcriber`
+
+~~~ts
+interface Transcriber {
+  transcribe(input: string, ...args: unknown[]): TranscribeResult
+}
+~~~
+
+具有 `transcribe` 方法，其接受字符串作为第一个参数、返回 `TranscribeResult` 的类型。本模块中的各转写器类都实现该接口。