Sync all projects

2026-07-28 12:25:15 +00:00
parent f80ebec583
commit fa0fa12a49
495 changed files with 367876 additions and 4483 deletions
@@ -0,0 +1,369 @@
+# pīnyīn (v4)
+
+pīnyīn, 汉字拼音转换工具。
+
+----
+
+[![NPM version][npm-badge]][npm-url]
+[![Build Status][build-badge]][build-url]
+[![Coverage Status][coveralls-badge]][coveralls-url]
+[![Language Grade: JavaScript][lgtm-badge]][lgtm-url]
+[![NPM downloads][npm-downloads]][npm-url]
+
+
+[npm-badge]: https://img.shields.io/npm/v/pinyin.svg?style=flat
+[npm-url]: https://www.npmjs.com/package/pinyin
+[npm-downloads]: http://img.shields.io/npm/dm/pinyin.svg?style=flat
+[build-badge]: https://github.com/hotoo/pinyin/actions/workflows/node.js.yml/badge.svg
+[build-url]: https://github.com/hotoo/pinyin/actions
+[coveralls-badge]: https://coveralls.io/repos/hotoo/pinyin/badge.svg?branch=master
+[coveralls-url]: https://coveralls.io/r/hotoo/pinyin
+[lgtm-badge]: https://img.shields.io/lgtm/grade/javascript/g/hotoo/pinyin.svg?logo=lgtm&logoWidth=18
+[lgtm-url]: https://lgtm.com/projects/g/hotoo/pinyin/context:javascript
+
+
+简体中文 | [English](https://pinyin.js.org/en-US/) | [한국어](https://pinyin.js.org/ko-KR/)
+
+
+转换中文字符为拼音。可以用于汉字注音、排序、检索。
+
+> 注：这个版本同时支持在 Node 和 Web 浏览器环境运行，
+>
+> Python 版请关注 [mozillazg/python-pinyin](https://github.com/mozillazg/python-pinyin)
+
+----
+
+## 特性
+
+* 根据词组智能匹配最正确的拼音。
+* 支持多音字。
+* 简单的繁体支持。
+* 支持多种不同拼音风格。
+
+## 安装
+
+via npm:
+
+```bash
+npm install pinyin --save
+```
+
+## 用法
+
+开发者：
+
+```typescript
+import pinyin from "pinyin";
+
+console.log(pinyin("中心"));    // [ [ 'zhōng' ], [ 'xīn' ] ]
+
+console.log(pinyin("中心", {
+  heteronym: true,              // 启用多音字模式
+}));                            // [ [ 'zhōng', 'zhòng' ], [ 'xīn' ] ]
+
+console.log(pinyin("中心", {
+  heteronym: true,              // 启用多音字模式
+  segment: true,                // 启用分词，以解决多音字问题。默认不开启，使用 true 开启使用 Intl.Segmenter 分词库。
+}));                            // [ [ 'zhōng' ], [ 'xīn' ] ]
+
+console.log(pinyin("中心", {
+  segment: "@node-rs/jieba",    // 指定分词库，可以是 "Intl.Segmenter", "nodejieba"、"segmentit"、"@node-rs/jieba"。
+}));                            // [ [ 'zhōng' ], [ 'xīn' ] ]
+
+console.log(pinyin("我喜欢你", {
+  segment: "segmentit",         // 启用分词
+  group: true,                  // 启用词组
+}));                            // [ [ 'wǒ' ], [ 'xǐhuān' ], [ 'nǐ' ] ]
+
+console.log(pinyin("中心", {
+  style: "initials",            // 设置拼音风格。
+  heteronym: true,              // 即使有多音字，因为拼音风格选择，重复的也会合并。
+}));                            // [ [ 'zh' ], [ 'x' ] ]
+
+console.log(pinyin("华夫人", {
+  mode: "surname",              // 姓名模式。
+}));                            // [ ['huà'], ['fū'], ['rén'] ]
+```
+
+命令行：
+
+```bash
+$ pinyin 中心
+zhōng xīn
+$ pinyin -h
+```
+
+## 类型
+
+### IPinyinOptions
+
+传入给 pinyin 方法的第二个参数的选项类型。
+
+```typescript
+export interface IPinyinOptions {
+  style?: IPinyinStyle; // 拼音输出形式
+  mode?: IPinyinMode, // 拼音模式
+  // 指定分词库。
+  // 为了兼容老版本，可以使用 boolean 类型指定是否开启分词，默认开启。
+  segment?: IPinyinSegment | boolean;
+  // 是否返回多音字
+  heteronym?: boolean;
+  // 是否分组词组拼音
+  group?: boolean;
+  compact?: boolean;
+}
+```
+
+### IPinyinStyle
+
+输出拼音格式。可以从直接使用以下字符串或数字，也兼容 v2 版本中 `pinyin.STYLE_TONE` 这样的形式。
+
+```typescript
+export type IPinyinStyle =
+  "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | "passport" | // 推荐使用小写，和输出的拼音一致
+  "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | "PASSPORT" | // 方便老版本迁移
+  0        | 1      | 2       | 5       | 3          | 4;               // 兼容老版本
+```
+
+### IPinyinMode
+
+拼音模式，默认普通模式，可以指定人名模式。
+
+```typescript
+// - NORMAL: 普通模式
+// - SURNAME: 姓氏模式，优先使用姓氏的拼音。
+export type IPinyinMode =
+  "normal" | "surname" |
+  "NORMAL" | "SURNAME";
+```
+
+### IPinyinSegment
+
+分词方式。
+
+- 默认关闭 `false`，
+- 也可以设置为 `true` 开启，Web 和 Node 版中均使用 "Intl.Segmenter" 分词。
+- 也可以声明以下字符串来指定分词算法。但目前 Web 版只支持 "Intl.Segmenter" 和 "segmentit" 分词。
+
+```typescript
+export type IPinyinSegment = "Intl.Segmenter" | "nodejieba" | "segmentit" | "@node-rs/jieba";
+```
+
+## API
+
+### 方法 `<Array> pinyin(words: string[, options: IPinyinOptions])`
+
+将传入的中文字符串 (words) 转换成拼音符号串。
+
+options 是可选的，可以设定拼音风格，或打开多音字选项。
+
+返回二维数组，第一维每个数组项位置对应每个中文字符串位置。
+第二维是各个汉字的读音列表，多音字会有多个拼音项。
+
+### 方法 `Number compare(a, b)`
+
+按拼音排序的默认算法。
+
+### 方法 `string[][] compact(pinyinResult array[][])`
+
+将拼音多音字以各种可能的组合排列变换成紧凑形式。参考 options.compact
+
+## 参数
+
+### `<Boolean|IPinyinSegment> options.segment`
+
+是否启用分词模式，中文分词有助于极大的降低多音字问题。
+但性能会极大的下降，内存也会使用更多。
+
+- 默认不启用分词。
+- 如果 `segemnt = true`，默认使用 Intl.Segmenter 分词。
+- 可以指定 "Intl.Segmenter"、"nodejieba"、"segmentit"、"@node-rs/jieba" 进行分词。
+
+### `<Boolean> options.heteronym`
+
+是否启用多音字模式，默认关闭。
+
+关闭多音字模式时，返回每个汉字第一个匹配的拼音。
+
+启用多音字模式时，返回多音字的所有拼音列表。
+
+### `<Boolean> options.group`
+
+按词组分组拼音，例如：
+
+```
+我喜欢你
+wǒ xǐhuān nǐ
+```
+
+### `<IPinyinStyle> options.style`
+
+指定拼音风格。可以使用以下特定字符串或数值指定：
+
+```typescript
+IPinyinStyle =
+  "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | "passport" | // 推荐使用小写，和输出的拼音一致
+  "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | "PASSPORT" | // 方便老版本迁移
+  0        | 1      | 2       | 5       | 3          | 4;               // 兼容老版本
+```
+
+
+#### `NORMAL`, `normal`
+
+普通风格，即不带声调。
+
+如：`pin yin`
+
+#### `TONE`, `tone`
+
+声调风格，拼音声调在韵母第一个字母上。
+
+注：这是默认的风格。
+
+如：`pīn yīn`
+
+#### `TONE2`, `tone2`
+
+声调风格 2，即拼音声调以数字形式在各个拼音之后，用数字 [0-4] 进行表示。
+
+如：`pin1 yin1`
+
+#### `TO3NE`, `to3ne`
+
+声调风格 3，即拼音声调以数字形式在注音字符之后，用数字 [0-4] 进行表示。
+
+如：`pi1n yi1n`
+
+#### `INITIALS`, `initials`
+
+声母风格，只返回各个拼音的声母部分。对于没有声母的汉字，返回空白字符串。
+
+如：`中国` 的拼音 `zh g`
+
+注：声母风格会区分 `zh` 和 `z`，`ch` 和 `c`，`sh` 和 `s`。
+
+注意：部分汉字没有声母，如 `啊`，`饿` 等，另外 `y`, `w`, `yu` 都不是声母，
+这些汉字的拼音声母风格会返回 `""`。请仔细考虑你的需求是否应该使用首字母风格。
+详情请参考 [为什么没有 y, w, yu 几个声母](#为什么没有 -y-w-yu- 几个声母)
+
+#### `FIRST_LETTER`, `first_letter`
+
+首字母风格，只返回拼音的首字母部分。
+
+如：`p y`
+
+#### `PASSPORT`, `passport`
+
+护照风格。转换成大写形式，并且 `ü` 会以 `YU` 形式输出。
+
+国家移民管理局门户网站于2021年9月29日发布了《关于内地居民拼音姓名中字母“ü”在出入境证件中打印规则的公告》（以下简称公告），根据《中国人名汉语拼音字母拼写规则》和《关于机读旅行证件的相关国际通用规范》， 内地居民申办出入境证件，出入境证件上打印的持证人拼音姓名中，Lü（吕等字）、Nü（女等字）中的字母“ü”应当转换为“YU”，LüE（略等字）、NüE（虐等字）中的字母“ü”应当转换为“U”。
+
+### <string> options.mode
+
+拼音模式，默认 "NORMAL" 普通模式。
+如果你明确的在姓名场景下，可以使用 "SURNAME" 让姓氏使用更准确的拼音。
+
+
+- `NORMAL`：普通模式，自动识别读音。
+- `SURNAME`：姓名模式，对于明确的姓名场景，可以更准确的识别姓氏的读音。
+
+### <boolean> options.compact
+
+是否返回紧凑模式，默认 false，按标准格式返回。
+如果设置为 true，则将多音字可能的各种组合排列后返回。例如：
+
+```
+pinyin("你好吗", { compact:false });
+> [[nǐ], [hǎo,hào], [ma,má,mǎ]]
+
+pinyin("你好吗", { compact:true });
+> [
+>   [nǐ,hǎo,ma], [nǐ,hǎo,má], [nǐ,hǎo,mǎ],
+>   [nǐ,hào,ma], [nǐ,hào,má], [nǐ,hào,mǎ],
+> ]
+```
+
+你也可以必要时使用 `compact()` 函数处理 `pinyin(han, {compact:false})` 返回的结果。
+
+## Test
+
+```bash
+npm test
+```
+
+## Q&A
+
+### 关于 Web 版如何使用
+
+首先，我建议大家应该优先考虑在服务端一次性转换拼音并将结果持久化，避免在客户端每次转换损耗性能和体验。
+
+如果你坚持在客户端使用，你可以考虑使用 [Webpack](http://webpack.github.io/) + [Babel](http://babeljs.io/) 来转换成低端浏览器的可执行代码。
+
+实在不想折腾，可以试试 https://www.jsdelivr.com/package/npm/pinyin
+
+### 为什么没有 `y`, `w`, `yu` 几个声母？
+
+声母风格（INITIALS）下，“雨”、“我”、“圆”等汉字返回空字符串，因为根据《汉语拼音方案》，
+`y`，`w`，`ü (yu)` 都不是声母，在某些特定韵母无声母时，才加上 `y` 或 `w`，而 `ü` 也有其特定规则。
+
+如果你觉得这个给你带来了麻烦，那么也请小心一些无声母的汉字（如“啊”、“饿”、“按”、“昂”等）。
+这时候你也许需要的是首字母风格（FIRST_LETTER）。
+
+### 如何实现按拼音排序？
+
+pinyin 模块提供了默认的排序方案：
+
+```js
+const pinyin = require('pinyin');
+
+const data = '我要排序'.split('');
+const sortedData = data.sort(pinyin.compare);
+```
+
+如果默认的比较方法不能满足你的需求，你可以自定义 pinyinCompare 方法：
+
+```js
+const pinyin = require('pinyin');
+
+const data = '我要排序'.split('');
+
+// 建议将汉字的拼音持久化存储起来。
+const pinyinData = data.map(han => ({
+  han: han,
+  pinyin: pinyin(han)[0][0], // 可以自行选择不同的生成拼音方案和风格。
+}));
+const sortedData = pinyinData.sort((a, b) => {
+  return a.pinyin.localeCompare(b.pinyin);
+}).map(d => d.han);
+```
+
+### node 版和 web 版有什么异同？
+
+`pinyin` 目前可以同时运行在 Node 服务器端和 Web 浏览器端。
+API 和使用方式完成一致。
+
+但 Web 版较 Node 版稍简单，拼音库只有常用字部分，没有使用分词算法，
+并且考虑了网络传输对词库进行了压缩处理。
+
+由于分词和繁体中文的特性，部分情况下的结果也不尽相同。
+
+| 特性         | Web 版                          | Node 版                           |
+|--------------|--------------------------------|----------------------------------|
+| 拼音库       | 常用字库。压缩、合并           | 完整字库。不压缩、合并           |
+| 分词         | 没有分词                       | 使用分词算法，多音字拼音更准确。 |
+| 拼音频度排序 | 有根据拼音使用频度优先级排序。 | 同 Web 版。                       |
+| 繁体中文     | 没有繁体中文支持。             | 有简单的繁简汉字转换。           |
+
+由于这些区别，测试不同运行环境的用例也不尽相同。
+
+## 捐赠
+
+如果这个模块有帮助到您，请 Star 这个仓库。
+
+你也可以选择使用支付宝或微信给我捐赠：
+
+<img src="https://hotoo.github.io/images/donate-hotoo.png" alt="Alipay:hotoo.cn@gmail.com, WeChat:hotoome" width="400" />
+
+## 许可证
+
+[MIT](http://hotoo.mit-license.org/)
@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+var commander = require('commander');
+
+commander.
+  version(require('../package').version).
+  usage('[options] 汉字').
+  option('-v, --version', 'output the version number').
+  option('-s, --style <style>', 'pinyin styles: [NORMAL,TONE,TONE2,INITIALS,FIRST_LETTER]').
+  option('-m, --mode <mode>', 'pinyin mode: [NORMAL,SURNAME]').
+  option('-S, --segment [segment]', 'segmentation word to phrases, support "Intl.Segmenter", "nodejieba", "@node-rs/jieba", "segmentit"').
+  option('-h, --heteronym', 'output heteronym pinyins').
+  option('-g, --group', 'output group by phrases').
+  option('-c, --compact', 'output the compact pinyin result').
+  option('-p, --separator <separator>', 'separator between words').
+  parse(process.argv);
+
+if (commander.list) {
+  process.exit();
+}
+
+// --segment <segment> 是可选项，当后面带的不合法的 segment 时，当作文本处理。
+const validSegmentList = ["Intl.Segmenter", "nodejieba", "@node-rs/jieba", "segmentit", true, false, undefined];
+if (!validSegmentList.includes(commander.segment)) {
+  commander.args.splice(0, 0, commander.segment);
+  commander.segment = true;
+}
+// output help and exit if no args found
+if (commander.args.length === 0) {
+  commander.help();
+}
+
+var pinyin = require("../").default;
+var options = {
+  style: commander.style || "TONE",
+  mode: commander.mode || "NORMAL",
+  heteronym: commander.heteronym || false,
+  group: commander.group || false,
+  segment: commander.segment || false,
+  compact: commander.compact || false,
+};
+
+var separator = commander.separator === undefined ? ' ' : commander.separator;
+var words = commander.args.join(" ");
+var py = pinyin(words, options).join(separator);
+console.log(py);
+
+// vim:ft=javascript
@@ -0,0 +1,53 @@
+import { ENUM_PINYIN_MODE, ENUM_PINYIN_STYLE } from "./constant";
+import type { IPinyinAllOptions, IPinyinOptions, IPinyinSegment, IPinyin } from "./declare";
+export default class PinyinBase {
+    STYLE_TONE: ENUM_PINYIN_STYLE;
+    STYLE_TONE2: ENUM_PINYIN_STYLE;
+    STYLE_TO3NE: ENUM_PINYIN_STYLE;
+    STYLE_NORMAL: ENUM_PINYIN_STYLE;
+    STYLE_INITIALS: ENUM_PINYIN_STYLE;
+    STYLE_FIRST_LETTER: ENUM_PINYIN_STYLE;
+    STYLE_PASSPORT: ENUM_PINYIN_STYLE;
+    MODE_NORMAL: ENUM_PINYIN_MODE;
+    MODE_SURNAME: ENUM_PINYIN_MODE;
+    /**
+     * 拼音转换入口。
+     */
+    pinyin(hans: string, options?: IPinyinOptions): string[][];
+    /**
+     * 不使用分词算法的拼音转换。
+     */
+    normal_pinyin(hans: string, options: IPinyinAllOptions): string[][];
+    /**
+     * 单字拼音转换。
+     * @param {String} han, 单个汉字
+     * @return {Array} 返回拼音列表，多音字会有多个拼音项。
+     */
+    single_pinyin(han: string, options: IPinyinAllOptions): string[];
+    segment(hans: string, segmentType?: IPinyinSegment): string[];
+    /**
+     * 将文本分词，并转换成拼音。
+     */
+    segment_pinyin(hans: string, options: IPinyinAllOptions): string[][];
+    /**
+     * 词语注音
+     * @param {String} phrases, 指定的词组。
+     * @param {Object} options, 选项。
+     * @return {Array}
+     */
+    phrases_pinyin(phrases: string, options: IPinyinAllOptions): string[][];
+    groupPhrases(phrases: string[][]): string[];
+    surname_pinyin(hans: string, options: IPinyinAllOptions): string[][];
+    compound_surname(hans: string, options: IPinyinAllOptions): string[][];
+    single_surname(hans: string, options: IPinyinAllOptions): string[][];
+    /**
+     * 比较两个汉字转成拼音后的排序顺序，可以用作默认的拼音排序算法。
+     *
+     * @param {String} hanA 汉字字符串 A。
+     * @return {String} hanB 汉字字符串 B。
+     * @return {Number} 返回 -1，0，或 1。
+     */
+    compare(hanA: string, hanB: string): number;
+    compact(pys: string[][]): string[][];
+}
+export declare function getPinyinInstance(py: PinyinBase): IPinyin;
@@ -0,0 +1,18 @@
+import type { IPinyinAllOptions } from "./declare";
+export declare enum ENUM_PINYIN_STYLE {
+    NORMAL = 0,
+    TONE = 1,
+    TONE2 = 2,
+    TO3NE = 5,
+    INITIALS = 3,
+    FIRST_LETTER = 4,
+    PASSPORT = 6
+}
+export declare enum ENUM_PINYIN_MODE {
+    NORMAL = 0,
+    SURNAME = 1
+}
+export declare const DEFAULT_OPTIONS: IPinyinAllOptions;
+export declare const PHONETIC_SYMBOL: Record<string, string>;
+export declare const INITIALS: string[];
+export declare const FINALS: string[];
@@ -0,0 +1,2 @@
+declare const _default: Record<string, string[][]>;
+export default _default;
@@ -0,0 +1,2 @@
+declare const dict: Record<number, string>;
+export default dict;
@@ -0,0 +1,2 @@
+declare const phrases_dict: Record<string, string[][]>;
+export default phrases_dict;
@@ -0,0 +1,2 @@
+declare const _default: Record<string, string[][]>;
+export default _default;
@@ -0,0 +1,36 @@
+import { ENUM_PINYIN_STYLE, ENUM_PINYIN_MODE } from "./constant";
+export interface IPinyin {
+    (han: string, options?: IPinyinOptions): string[][];
+    compare: (a: string, b: string) => number;
+    compact: (arr: string[][]) => string[][];
+    STYLE_TONE: ENUM_PINYIN_STYLE;
+    STYLE_TONE2: ENUM_PINYIN_STYLE;
+    STYLE_TO3NE: ENUM_PINYIN_STYLE;
+    STYLE_NORMAL: ENUM_PINYIN_STYLE;
+    STYLE_INITIALS: ENUM_PINYIN_STYLE;
+    STYLE_FIRST_LETTER: ENUM_PINYIN_STYLE;
+    STYLE_PASSPORT: ENUM_PINYIN_STYLE;
+    MODE_NORMAL: ENUM_PINYIN_MODE;
+    MODE_SURNAME: ENUM_PINYIN_MODE;
+}
+export type IPinyinStyle = ENUM_PINYIN_STYLE | "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | "passport" | // 推荐使用小写，和输出的拼音一致
+"NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | "PASSPORT" | // 方便老版本迁移
+0 | 1 | 2 | 5 | 3 | 4;
+export type IPinyinMode = ENUM_PINYIN_MODE | "normal" | "surname" | "NORMAL" | "SURNAME";
+export type IPinyinSegment = "nodejieba" | "segmentit" | "@node-rs/jieba" | "Intl.Segmenter";
+export interface IPinyinAllOptions {
+    style: ENUM_PINYIN_STYLE;
+    mode: ENUM_PINYIN_MODE;
+    segment?: IPinyinSegment;
+    heteronym: boolean;
+    group: boolean;
+    compact: boolean;
+}
+export interface IPinyinOptions {
+    style?: IPinyinStyle;
+    mode?: IPinyinMode;
+    segment?: IPinyinSegment | boolean;
+    heteronym?: boolean;
+    group?: boolean;
+    compact?: boolean;
+}
@@ -0,0 +1,9 @@
+import { ENUM_PINYIN_STYLE } from "./constant";
+/**
+ * 格式化拼音风格。
+ *
+ * @param {string} pinyin TONE 风格的拼音。
+ * @param {ENUM_PINYIN_STYLE} style 目标转换的拼音风格。
+ * @return {string} 转换后的拼音。
+ */
+export declare function toFixed(pinyin: string, style: ENUM_PINYIN_STYLE): string;
@@ -0,0 +1,2 @@
+declare const phonetic_symbol: Record<string, string>;
+export default phonetic_symbol;
@@ -0,0 +1,7 @@
+import PinyinBase from "./PinyinBase";
+export declare class Pinyin extends PinyinBase {
+}
+export declare const pinyin: import("./declare").IPinyin;
+export default pinyin;
+export declare const compare: (a: string, b: string) => number;
+export { compact } from "./util";
@@ -0,0 +1,9 @@
+import PinyinBase from "./PinyinBase";
+import type { IPinyinSegment } from "./declare";
+export declare class Pinyin extends PinyinBase {
+    segment(hans: string, segmentType?: IPinyinSegment): string[];
+}
+export declare const pinyin: import("./declare").IPinyin;
+export default pinyin;
+export declare const compare: (a: string, b: string) => number;
+export { compact } from "./util";
@@ -0,0 +1,6 @@
+import type { IPinyinSegment } from "./declare";
+/**
+ * TODO: 分词并带词性信息，需要调整 segment_pinyin 方法。
+ * 分词并标注词性。
+ */
+export declare function segment(hans: string, segment?: IPinyinSegment): string[];
@@ -0,0 +1,6 @@
+import type { IPinyinSegment } from "./declare";
+/**
+ * TODO: 分词并带词性信息，需要调整 segment_pinyin 方法。
+ * 分词并标注词性。
+ */
+export declare function segment(hans: string, segment?: IPinyinSegment): string[];
@@ -0,0 +1,31 @@
+import type { IPinyinAllOptions, IPinyinOptions, IPinyinStyle, IPinyinMode } from "./declare";
+import { ENUM_PINYIN_STYLE, ENUM_PINYIN_MODE } from "./constant";
+export declare function hasKey(obj: any, key: string): boolean;
+export declare function convertPinyinStyle(style?: IPinyinStyle): ENUM_PINYIN_STYLE;
+export declare function convertPinyinMode(mode?: IPinyinMode): ENUM_PINYIN_MODE;
+export declare function convertUserOptions(options?: IPinyinOptions): IPinyinAllOptions;
+/**
+ * 组合 2 个拼音数组。
+ * @param {string[]} a1 第一个数组，形如 ["zhāo", "cháo"]
+ * @param {string[]} a2 字符串型数组。形如 ["yáng"]
+ * @return {string[]} 组合后的一维数组，如上可得 ["zhāoyáng", "cháoyáng"]
+ */
+export declare function combo2array(a1: string[], a2: string[]): string[];
+/**
+ * 合并二维元祖。
+ * @param {string[][]} arr 二维元祖 [["zhāo", "cháo"], ["yáng"], ["dōng"], ["shēng"]]
+ * @return {string[]} 返回二维字符串组合数组。形如
+ *  [
+ *    ["zhāoyáng"], ["dōng"], ["shēng"],
+ *    ["cháoyáng"], ["dōng"], ["shēng"]
+ *  ]
+ */
+export declare function combo(arr: string[][]): string[];
+/**
+ * 组合两个拼音数组，形成一个新的二维数组
+ * @param {string[]|string[][]} arr1 eg: ["hai", "huan"]
+ * @param {string[]} arr2 eg: ["qian"]
+ * @returns {string[][]} 组合后的二维数组，eg: [ ["hai", "qian"], ["huan", "qian"] ]
+ */
+export declare function compact2array(a1: string[] | string[][], a2: string[]): string[][];
+export declare function compact(arr: string[][]): string[][];
@@ -0,0 +1,53 @@
+import { ENUM_PINYIN_MODE, ENUM_PINYIN_STYLE } from "./constant";
+import type { IPinyinAllOptions, IPinyinOptions, IPinyinSegment, IPinyin } from "./declare";
+export default class PinyinBase {
+    STYLE_TONE: ENUM_PINYIN_STYLE;
+    STYLE_TONE2: ENUM_PINYIN_STYLE;
+    STYLE_TO3NE: ENUM_PINYIN_STYLE;
+    STYLE_NORMAL: ENUM_PINYIN_STYLE;
+    STYLE_INITIALS: ENUM_PINYIN_STYLE;
+    STYLE_FIRST_LETTER: ENUM_PINYIN_STYLE;
+    STYLE_PASSPORT: ENUM_PINYIN_STYLE;
+    MODE_NORMAL: ENUM_PINYIN_MODE;
+    MODE_SURNAME: ENUM_PINYIN_MODE;
+    /**
+     * 拼音转换入口。
+     */
+    pinyin(hans: string, options?: IPinyinOptions): string[][];
+    /**
+     * 不使用分词算法的拼音转换。
+     */
+    normal_pinyin(hans: string, options: IPinyinAllOptions): string[][];
+    /**
+     * 单字拼音转换。
+     * @param {String} han, 单个汉字
+     * @return {Array} 返回拼音列表，多音字会有多个拼音项。
+     */
+    single_pinyin(han: string, options: IPinyinAllOptions): string[];
+    segment(hans: string, segmentType?: IPinyinSegment): string[];
+    /**
+     * 将文本分词，并转换成拼音。
+     */
+    segment_pinyin(hans: string, options: IPinyinAllOptions): string[][];
+    /**
+     * 词语注音
+     * @param {String} phrases, 指定的词组。
+     * @param {Object} options, 选项。
+     * @return {Array}
+     */
+    phrases_pinyin(phrases: string, options: IPinyinAllOptions): string[][];
+    groupPhrases(phrases: string[][]): string[];
+    surname_pinyin(hans: string, options: IPinyinAllOptions): string[][];
+    compound_surname(hans: string, options: IPinyinAllOptions): string[][];
+    single_surname(hans: string, options: IPinyinAllOptions): string[][];
+    /**
+     * 比较两个汉字转成拼音后的排序顺序，可以用作默认的拼音排序算法。
+     *
+     * @param {String} hanA 汉字字符串 A。
+     * @return {String} hanB 汉字字符串 B。
+     * @return {Number} 返回 -1，0，或 1。
+     */
+    compare(hanA: string, hanB: string): number;
+    compact(pys: string[][]): string[][];
+}
+export declare function getPinyinInstance(py: PinyinBase): IPinyin;
@@ -0,0 +1,18 @@
+import type { IPinyinAllOptions } from "./declare";
+export declare enum ENUM_PINYIN_STYLE {
+    NORMAL = 0,
+    TONE = 1,
+    TONE2 = 2,
+    TO3NE = 5,
+    INITIALS = 3,
+    FIRST_LETTER = 4,
+    PASSPORT = 6
+}
+export declare enum ENUM_PINYIN_MODE {
+    NORMAL = 0,
+    SURNAME = 1
+}
+export declare const DEFAULT_OPTIONS: IPinyinAllOptions;
+export declare const PHONETIC_SYMBOL: Record<string, string>;
+export declare const INITIALS: string[];
+export declare const FINALS: string[];
@@ -0,0 +1,2 @@
+declare const _default: Record<string, string[][]>;
+export default _default;
@@ -0,0 +1,2 @@
+declare const dict: Record<number, string>;
+export default dict;
@@ -0,0 +1,2 @@
+declare const phrases_dict: Record<string, string[][]>;
+export default phrases_dict;
@@ -0,0 +1,2 @@
+declare const _default: Record<string, string[][]>;
+export default _default;
@@ -0,0 +1,36 @@
+import { ENUM_PINYIN_STYLE, ENUM_PINYIN_MODE } from "./constant";
+export interface IPinyin {
+    (han: string, options?: IPinyinOptions): string[][];
+    compare: (a: string, b: string) => number;
+    compact: (arr: string[][]) => string[][];
+    STYLE_TONE: ENUM_PINYIN_STYLE;
+    STYLE_TONE2: ENUM_PINYIN_STYLE;
+    STYLE_TO3NE: ENUM_PINYIN_STYLE;
+    STYLE_NORMAL: ENUM_PINYIN_STYLE;
+    STYLE_INITIALS: ENUM_PINYIN_STYLE;
+    STYLE_FIRST_LETTER: ENUM_PINYIN_STYLE;
+    STYLE_PASSPORT: ENUM_PINYIN_STYLE;
+    MODE_NORMAL: ENUM_PINYIN_MODE;
+    MODE_SURNAME: ENUM_PINYIN_MODE;
+}
+export type IPinyinStyle = ENUM_PINYIN_STYLE | "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | "passport" | // 推荐使用小写，和输出的拼音一致
+"NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | "PASSPORT" | // 方便老版本迁移
+0 | 1 | 2 | 5 | 3 | 4;
+export type IPinyinMode = ENUM_PINYIN_MODE | "normal" | "surname" | "NORMAL" | "SURNAME";
+export type IPinyinSegment = "nodejieba" | "segmentit" | "@node-rs/jieba" | "Intl.Segmenter";
+export interface IPinyinAllOptions {
+    style: ENUM_PINYIN_STYLE;
+    mode: ENUM_PINYIN_MODE;
+    segment?: IPinyinSegment;
+    heteronym: boolean;
+    group: boolean;
+    compact: boolean;
+}
+export interface IPinyinOptions {
+    style?: IPinyinStyle;
+    mode?: IPinyinMode;
+    segment?: IPinyinSegment | boolean;
+    heteronym?: boolean;
+    group?: boolean;
+    compact?: boolean;
+}
@@ -0,0 +1,9 @@
+import { ENUM_PINYIN_STYLE } from "./constant";
+/**
+ * 格式化拼音风格。
+ *
+ * @param {string} pinyin TONE 风格的拼音。
+ * @param {ENUM_PINYIN_STYLE} style 目标转换的拼音风格。
+ * @return {string} 转换后的拼音。
+ */
+export declare function toFixed(pinyin: string, style: ENUM_PINYIN_STYLE): string;
@@ -0,0 +1,2 @@
+declare const phonetic_symbol: Record<string, string>;
+export default phonetic_symbol;
@@ -0,0 +1,7 @@
+import PinyinBase from "./PinyinBase";
+export declare class Pinyin extends PinyinBase {
+}
+export declare const pinyin: import("./declare").IPinyin;
+export default pinyin;
+export declare const compare: (a: string, b: string) => number;
+export { compact } from "./util";
@@ -0,0 +1,9 @@
+import PinyinBase from "./PinyinBase";
+import type { IPinyinSegment } from "./declare";
+export declare class Pinyin extends PinyinBase {
+    segment(hans: string, segmentType?: IPinyinSegment): string[];
+}
+export declare const pinyin: import("./declare").IPinyin;
+export default pinyin;
+export declare const compare: (a: string, b: string) => number;
+export { compact } from "./util";
@@ -0,0 +1,6 @@
+import type { IPinyinSegment } from "./declare";
+/**
+ * TODO: 分词并带词性信息，需要调整 segment_pinyin 方法。
+ * 分词并标注词性。
+ */
+export declare function segment(hans: string, segment?: IPinyinSegment): string[];
@@ -0,0 +1,6 @@
+import type { IPinyinSegment } from "./declare";
+/**
+ * TODO: 分词并带词性信息，需要调整 segment_pinyin 方法。
+ * 分词并标注词性。
+ */
+export declare function segment(hans: string, segment?: IPinyinSegment): string[];
@@ -0,0 +1,31 @@
+import type { IPinyinAllOptions, IPinyinOptions, IPinyinStyle, IPinyinMode } from "./declare";
+import { ENUM_PINYIN_STYLE, ENUM_PINYIN_MODE } from "./constant";
+export declare function hasKey(obj: any, key: string): boolean;
+export declare function convertPinyinStyle(style?: IPinyinStyle): ENUM_PINYIN_STYLE;
+export declare function convertPinyinMode(mode?: IPinyinMode): ENUM_PINYIN_MODE;
+export declare function convertUserOptions(options?: IPinyinOptions): IPinyinAllOptions;
+/**
+ * 组合 2 个拼音数组。
+ * @param {string[]} a1 第一个数组，形如 ["zhāo", "cháo"]
+ * @param {string[]} a2 字符串型数组。形如 ["yáng"]
+ * @return {string[]} 组合后的一维数组，如上可得 ["zhāoyáng", "cháoyáng"]
+ */
+export declare function combo2array(a1: string[], a2: string[]): string[];
+/**
+ * 合并二维元祖。
+ * @param {string[][]} arr 二维元祖 [["zhāo", "cháo"], ["yáng"], ["dōng"], ["shēng"]]
+ * @return {string[]} 返回二维字符串组合数组。形如
+ *  [
+ *    ["zhāoyáng"], ["dōng"], ["shēng"],
+ *    ["cháoyáng"], ["dōng"], ["shēng"]
+ *  ]
+ */
+export declare function combo(arr: string[][]): string[];
+/**
+ * 组合两个拼音数组，形成一个新的二维数组
+ * @param {string[]|string[][]} arr1 eg: ["hai", "huan"]
+ * @param {string[]} arr2 eg: ["qian"]
+ * @returns {string[][]} 组合后的二维数组，eg: [ ["hai", "qian"], ["huan", "qian"] ]
+ */
+export declare function compact2array(a1: string[] | string[][], a2: string[]): string[][];
+export declare function compact(arr: string[][]): string[][];
@@ -0,0 +1,124 @@
+{
+  "name": "pinyin",
+  "version": "4.0.0",
+  "description": "汉语拼音转换工具。",
+  "types": "./lib/types/pinyin.d.ts",
+  "main": "./lib/cjs/pinyin.js",
+  "module": "./lib/esm/pinyin.js",
+  "browser": "./lib/umd/pinyin.js",
+  "bin": {
+    "pinyin": "./bin/pinyin"
+  },
+  "homepage": "https://pinyin.js.org/",
+  "author": "闲耘 <[email protected]>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hotoo/pinyin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hotoo/pinyin/issues"
+  },
+  "scripts": {
+    "start": "dumi dev",
+    "prepublishOnly": "pnpm build",
+    "build": "pnpm build:rollup",
+    "build:rollup": "rm -rf lib && rollup -c",
+    "build:tsup": "tsup src/pinyin.ts src/pinyin-web.ts --format cjs,esm --global-name pinyin --dts --out-dir lib",
+    "build:tsc": "tsc --downlevelIteration -p tsconfig-es5.json & tsc --downlevelIteration -p tsconfig.json & pnpm build:amd",
+    "build:amd": "tsc --downlevelIteration -p tsconfig-amd.json",
+    "doc:build": "rm -rf ./.dumi ./docs-dist && dumi build && cp CNAME docs-dist",
+    "doc:deploy": "pnpm doc:build && gh-pages -d docs-dist",
+    "lint": "eslint ./src/ ./test/",
+    "test": "jest --coverage",
+    "debug": "npx ts-node tools/debug.ts"
+  },
+  "dependencies": {
+    "commander": "~1.1.1"
+  },
+  "peerDependencies": {
+    "@node-rs/jieba": "^1.6.0",
+    "nodejieba": "^3.4.4",
+    "segmentit": "^2.0.3"
+  },
+  "peerDependenciesMeta": {
+    "@node-rs/jieba": {
+      "optional": true
+    },
+    "nodejieba": {
+      "optional": true
+    },
+    "segmentit": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@babel/preset-env": "^7.15.6",
+    "@babel/preset-typescript": "^7.15.0",
+    "@rollup/plugin-commonjs": "^17.1.0",
+    "@rollup/plugin-json": "^4.1.0",
+    "@rollup/plugin-node-resolve": "^11.2.0",
+    "@textea/json-viewer": "^4.0.1",
+    "@types/jest": "^27.0.2",
+    "@types/node": "^22.15.17",
+    "@typescript-eslint/eslint-plugin": "^5.14.0",
+    "@typescript-eslint/parser": "^5.14.0",
+    "aurl": "^1.2.0",
+    "aws-sdk": "^2.1011.0",
+    "beautify-benchmark": "^0.2.4",
+    "benchmark": "~1.0.0",
+    "dumi": "^2.4.21",
+    "eslint": "^8.11.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-import-resolver-typescript": "^2.5.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "gh-pages": "^3.2.3",
+    "jest": "^27.2.3",
+    "mock-aws-s3": "^4.0.2",
+    "nock": "^13.1.4",
+    "npx": "^10.2.2",
+    "prettier": "^2.6.0",
+    "request": "~2.68.0",
+    "rollup": "2.60.0",
+    "rollup-plugin-alias": "^2.2.0",
+    "rollup-plugin-cleanup": "^3.2.1",
+    "rollup-plugin-terser": "^7.0.2",
+    "rollup-plugin-typescript2": "^0.34.1",
+    "ts-node": "^10.5.0",
+    "tsup": "^8.4.0",
+    "typescript": "^4.4.4"
+  },
+  "registry": "https://registry.npmmirror.com",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "package.json",
+    "build/",
+    "bin",
+    "data",
+    "lib",
+    "esm",
+    "amd",
+    "index.js"
+  ],
+  "keywords": [
+    "拼音",
+    "汉语",
+    "汉字",
+    "中文",
+    "Pinyin"
+  ],
+  "directories": {
+    "example": "examples",
+    "test": "test"
+  },
+  "engines": {
+    "install-node": "^18.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "nodejieba"
+    ]
+  },
+  "license": "MIT"
+}