parse-pinyin 1.3.2 → 1.3.4

package/README.md

@@ -1,252 +1,252 @@
-# parse-pinyin
-
-[![NPM version](https://img.shields.io/npm/v/parse-pinyin.svg?style=flat-square)](https://npmjs.org/package/parse-pinyin)
-[![NPM downloads](https://img.shields.io/npm/dm/parse-pinyin.svg?style=flat-square)](https://npmjs.org/package/parse-pinyin)
-[![License](https://img.shields.io/npm/l/parse-pinyin.svg?style=flat-square)](https://github.com/your-username/parse-pinyin/blob/main/LICENSE)
-
-一个高效的汉字拼音查询库，使用极致优化的 JSON 格式存储拼音数据，支持多种输出格式和反向查询功能，并提供拼音解析为声母、韵母和声调的能力。
-
-## 特性
-
-- 🚀 **高性能**: 预处理数据结构，查询速度快
-- 📦 **轻量级**: 无外部依赖，包体积小
-- 🌐 **多格式支持**: 支持声调符号、数字声调、数组格式等多种输出
-- 🔁 **双向查询**: 支持汉字查拼音和拼音查汉字
-- 🧩 **混合输入支持**: 支持包含汉字和非汉字字符的字符串处理
-- 🔍 **拼音解析**: 支持将拼音解析为声母、韵母和声调、韵母类型、整体认读类型
-- 📱 **跨平台**: 支持 Node.js、浏览器和 Webpack/Vite 等构建工具
-
-## 安装
-
-```bash
-npm install parse-pinyin
-```
-
-## 快速开始
-
-```javascript
-import { toPinyin, toHanzi, parse } from 'parse-pinyin';
-
-// 汉字转拼音 (默认格式 - 带声调符号)
-console.log(toPinyin('中')); 
-// 输出: ["zhōng", "zhòng"]
-
-// 汉字转拼音 (数字声调格式)
-console.log(toPinyin('中', { toneType: 'number' })); 
-// 输出: ["zhong1", "zhong4"]
-
-// 汉字转拼音 (数组格式)
-console.log(toPinyin('中', { toneType: 'array' })); 
-// 输出: [["zhong", 1], ["zhong", 4]]
-
-// 汉字转拼音 (无音调格式)
-console.log(toPinyin('中', { tone: false })); 
-// 输出: ["zhong", "zhong"]
-
-// 拼音反查汉字
-console.log(toHanzi('xíng')); 
-// 输出: ["行", "形", "型", ...]
-
-// 解析拼音为声母、韵母和声调
-console.log(parse('zhōng'));
-// 输出: { shengmu: 'zh', yunmu: 'ong', shengdiao: 1 }
-console.log(parse('ān'));
-// 输出: { shengmu: '', yunmu: 'an', shengdiao: 1 }
-console.log(parse('yi'));
-// 输出: { shengmu: 'y', yunmu: 'i', shengdiao: 0 }
-console.log(parse('invalid'));
-// 输出: null
-```
-
-## API 参考
-
-### `toPinyin(char: string, options?: ToneOptions)`
-
-将汉字或字符串转换为拼音。
-
-#### 参数
-
-- `char`: 输入的字符或字符串（可以包含非汉字字符）
-- `options`: 音调选项
-  - `tone`: 是否保留音调 (默认: `true`)
-  - `toneType`: 音调表示方式
-    - `'symbol'`: 声调符号 (默认)
-    - `'number'`: 数字声调
-    - `'array'`: 数组格式 `[拼音, 声调数字]`
-
-#### 返回值
-
-- 如果输入是单个汉字，返回其拼音数组。
-- 如果输入是字符串，返回一个混合数组（汉字对应的拼音数组 + 非汉字字符）。
-
-#### 示例
-
-```javascript
-// 单个汉字
-console.log(toPinyin('中'));
-// 输出: ["zhōng", "zhòng"]
-
-// 包含非汉字字符的字符串
-console.log(toPinyin('Hello, 世界'));
-// 输出: ['H', 'e', 'l', 'l', 'o', ',', ' ', 'shì', 'jiè']
-```
-
----
-
-### `toHanzi(pinyin: string)`
-
-根据拼音查询匹配的汉字。
-
-#### 参数
-
-- `pinyin`: 要查询的拼音（可以带声调符号）
-
-#### 返回值
-
-- `string[]`: 匹配该拼音的所有汉字组成的数组
-
-#### 示例
-
-```javascript
-console.log(toHanzi('zhōng'));
-// 输出: ['中']
-console.log(toHanzi('yī'));
-// 输出: ['一', '衣', ...]
-```
-
----
-
-### `parse(pinyin: string)`
-
-解析拼音为声母、韵母和声调。
-
-#### 参数
-
-- `pinyin`: 要解析的拼音（可以带声调符号）
-
-#### 返回值
-
-- `{ shengmu: string, yunmu: string, shengdiao: number } | null`
-  - `shengmu`: 声母部分
-  - `yunmu`: 韵母部分
-  - `shengdiao`: 声调数字（1-5，5 表示轻声）
-
-如果输入无效或无法解析，则返回 `null`。
-
-#### 示例
-
-```javascript
-console.log(parse('zhōng'));
-// 输出: { shengmu: 'zh', yunmu: 'ong', shengdiao: 1,yunmuType: '后鼻韵母'}
-console.log(parse('ān'));
-// 输出: { shengmu: '', yunmu: 'an', shengdiao: 1,yunmuType: '前鼻韵母', }
-console.log(parse('yi'));
-// 输出: { shengmu: 'y', yunmu: 'i', shengdiao: 0,zhengtirendu: '舌面音及其他' }
-console.log(parse('invalid'));
-// 输出: null
-```
-
----
-
-## 性能对比
-
-在典型的使用场景中，`parse-pinyin` 相比其他拼音库具有显著的性能优势：
-
-### 与 pinyin-pro 对比
-
-实际测试结果（硬件：Apple M1 Pro，Node.js v18.17.0）：
-
-```javascript
-// 测试代码
-import { toPinyin } from 'parse-pinyin';
-import { pinyin } from 'pinyin-pro';
-
-const testChars = ['一', '二', '三', '四', '五', '六', '七', '八', '九', '十',
-                  '中', '国', '人', '民', '大', '家', '好', '学', '习', '天',
-                  '行', '动', '快', '乐', '幸', '福', '健', '康', '安', '全'];
-
-console.time('parse-pinyin');
-for (let i = 0; i < 10000; i++) {
-  testChars.forEach(char => {
-    toPinyin(char);
-  });
-}
-console.timeEnd('parse-pinyin');
-// 输出: parse-pinyin: 13.269ms
-
-console.time('pinyin-pro');
-for (let i = 0; i < 10000; i++) {
-  testChars.forEach(char => {
-    pinyin(char, { toneType: 'symbol' });
-  });
-}
-console.timeEnd('pinyin-pro');
-// 输出: pinyin-pro: 166.447ms
-```
-
-### 性能测试结果
-
-| 测试项目 | parse-pinyin | pinyin-pro | 性能提升 |
-|----------|--------------|------------|----------|
-| 单字符拼音转换 (10,000次) | 13.27ms | 166.45ms | 12.54x |
-| 批量处理 (100,000字符) | ~130ms | ~1660ms | 12.77x |
-
-### 文件大小
-
-| parse-pinyin | pinyin-pro | 
-|--------------|------------|
-| 229 kB | 323 kB |
-
----
-
-## 浏览器使用
-
-```html
-<script src="https://unpkg.com/parse-pinyin@latest/dist/index.global.js"></script>
-<script>
-  console.log(pinyin.toPinyin('中')); // ["zhōng", "zhòng"]
-  console.log(pinyin.toHanzi('xíng')); // ["行", "形", "型", ...]
-</script>
-```
-
----
-
-## Node.js 使用
-
-```javascript
-const { toPinyin, toHanzi, parse } = require('parse-pinyin');
-
-console.log(toPinyin('中')); // ["zhōng", "zhòng"]
-console.log(toHanzi('xíng')); // ["行", "形", "型", ...]
-console.log(parse('zhōng')); // { shengmu: 'zh', yunmu: 'ong', shengdiao: 1 }
-```
-
----
-
-## 构建和开发
-
-```bash
-# 安装依赖
-npm install
-
-# 构建项目
-npm run build
-
-# 运行测试
-npm test
-
-# 运行基准测试
-npm run bench
-```
-
----
-
-## 数据来源
-
-拼音数据来源于 CC-CEDICT 词典，经过预处理和优化以适应高性能查询需求。
-
----
-
-## 许可证
-
+# parse-pinyin
+
+[![NPM version](https://img.shields.io/npm/v/parse-pinyin.svg?style=flat-square)](https://npmjs.org/package/parse-pinyin)
+[![NPM downloads](https://img.shields.io/npm/dm/parse-pinyin.svg?style=flat-square)](https://npmjs.org/package/parse-pinyin)
+[![License](https://img.shields.io/npm/l/parse-pinyin.svg?style=flat-square)](https://github.com/your-username/parse-pinyin/blob/main/LICENSE)
+
+一个高效的汉字拼音查询库，使用极致优化的 JSON 格式存储拼音数据，支持多种输出格式和反向查询功能，并提供拼音解析为声母、韵母和声调的能力。
+
+## 特性
+
+- 🚀 **高性能**: 预处理数据结构，查询速度快
+- 📦 **轻量级**: 无外部依赖，包体积小
+- 🌐 **多格式支持**: 支持声调符号、数字声调、数组格式等多种输出
+- 🔁 **双向查询**: 支持汉字查拼音和拼音查汉字
+- 🧩 **混合输入支持**: 支持包含汉字和非汉字字符的字符串处理
+- 🔍 **拼音解析**: 支持将拼音解析为声母、韵母和声调、韵母类型、整体认读类型
+- 📱 **跨平台**: 支持 Node.js、浏览器和 Webpack/Vite 等构建工具
+
+## 安装
+
+```bash
+npm install parse-pinyin
+```
+
+## 快速开始
+
+```javascript
+import { toPinyin, toHanzi, parse } from 'parse-pinyin';
+
+// 汉字转拼音 (默认格式 - 带声调符号)
+console.log(toPinyin('中')); 
+// 输出: ["zhōng", "zhòng"]
+
+// 汉字转拼音 (数字声调格式)
+console.log(toPinyin('中', { toneType: 'number' })); 
+// 输出: ["zhong1", "zhong4"]
+
+// 汉字转拼音 (数组格式)
+console.log(toPinyin('中', { toneType: 'array' })); 
+// 输出: [["zhong", 1], ["zhong", 4]]
+
+// 汉字转拼音 (无音调格式)
+console.log(toPinyin('中', { tone: false })); 
+// 输出: ["zhong", "zhong"]
+
+// 拼音反查汉字
+console.log(toHanzi('xíng')); 
+// 输出: ["行", "形", "型", ...]
+
+// 解析拼音为声母、韵母和声调
+console.log(parse('zhōng'));
+// 输出: { shengmu: 'zh', yunmu: 'ong', shengdiao: 1 }
+console.log(parse('ān'));
+// 输出: { shengmu: '', yunmu: 'an', shengdiao: 1 }
+console.log(parse('yi'));
+// 输出: { shengmu: 'y', yunmu: 'i', shengdiao: 0 }
+console.log(parse('invalid'));
+// 输出: null
+```
+
+## API 参考
+
+### `toPinyin(char: string, options?: ToneOptions)`
+
+将汉字或字符串转换为拼音。
+
+#### 参数
+
+- `char`: 输入的字符或字符串（可以包含非汉字字符）
+- `options`: 音调选项
+  - `tone`: 是否保留音调 (默认: `true`)
+  - `toneType`: 音调表示方式
+    - `'symbol'`: 声调符号 (默认)
+    - `'number'`: 数字声调
+    - `'array'`: 数组格式 `[拼音, 声调数字]`
+
+#### 返回值
+
+- 如果输入是单个汉字，返回其拼音数组。
+- 如果输入是字符串，返回一个混合数组（汉字对应的拼音数组 + 非汉字字符）。
+
+#### 示例
+
+```javascript
+// 单个汉字
+console.log(toPinyin('中'));
+// 输出: ["zhōng", "zhòng"]
+
+// 包含非汉字字符的字符串
+console.log(toPinyin('Hello, 世界'));
+// 输出: ['H', 'e', 'l', 'l', 'o', ',', ' ', 'shì', 'jiè']
+```
+
+---
+
+### `toHanzi(pinyin: string)`
+
+根据拼音查询匹配的汉字。
+
+#### 参数
+
+- `pinyin`: 要查询的拼音（可以带声调符号）
+
+#### 返回值
+
+- `string[]`: 匹配该拼音的所有汉字组成的数组
+
+#### 示例
+
+```javascript
+console.log(toHanzi('zhōng'));
+// 输出: ['中']
+console.log(toHanzi('yī'));
+// 输出: ['一', '衣', ...]
+```
+
+---
+
+### `parse(pinyin: string)`
+
+解析拼音为声母、韵母和声调。
+
+#### 参数
+
+- `pinyin`: 要解析的拼音（可以带声调符号）
+
+#### 返回值
+
+- `{ shengmu: string, yunmu: string, shengdiao: number } | null`
+  - `shengmu`: 声母部分
+  - `yunmu`: 韵母部分
+  - `shengdiao`: 声调数字（1-5，5 表示轻声）
+
+如果输入无效或无法解析，则返回 `null`。
+
+#### 示例
+
+```javascript
+console.log(parse('zhōng'));
+// 输出: { shengmu: 'zh', yunmu: 'ong', shengdiao: 1,yunmuType: '后鼻韵母'}
+console.log(parse('ān'));
+// 输出: { shengmu: '', yunmu: 'an', shengdiao: 1,yunmuType: '前鼻韵母', }
+console.log(parse('yi'));
+// 输出: { shengmu: 'y', yunmu: 'i', shengdiao: 0,zhengtirendu: '舌面音及其他' }
+console.log(parse('invalid'));
+// 输出: null
+```
+
+---
+
+## 性能对比
+
+在典型的使用场景中，`parse-pinyin` 相比其他拼音库具有显著的性能优势：
+
+### 与 pinyin-pro 对比
+
+实际测试结果（硬件：Apple M1 Pro，Node.js v18.17.0）：
+
+```javascript
+// 测试代码
+import { toPinyin } from 'parse-pinyin';
+import { pinyin } from 'pinyin-pro';
+
+const testChars = ['一', '二', '三', '四', '五', '六', '七', '八', '九', '十',
+                  '中', '国', '人', '民', '大', '家', '好', '学', '习', '天',
+                  '行', '动', '快', '乐', '幸', '福', '健', '康', '安', '全'];
+
+console.time('parse-pinyin');
+for (let i = 0; i < 10000; i++) {
+  testChars.forEach(char => {
+    toPinyin(char);
+  });
+}
+console.timeEnd('parse-pinyin');
+// 输出: parse-pinyin: 13.269ms
+
+console.time('pinyin-pro');
+for (let i = 0; i < 10000; i++) {
+  testChars.forEach(char => {
+    pinyin(char, { toneType: 'symbol' });
+  });
+}
+console.timeEnd('pinyin-pro');
+// 输出: pinyin-pro: 166.447ms
+```
+
+### 性能测试结果
+
+| 测试项目 | parse-pinyin | pinyin-pro | 性能提升 |
+|----------|--------------|------------|----------|
+| 单字符拼音转换 (10,000次) | 13.27ms | 166.45ms | 12.54x |
+| 批量处理 (100,000字符) | ~130ms | ~1660ms | 12.77x |
+
+### 文件大小
+
+| parse-pinyin | pinyin-pro | 
+|--------------|------------|
+| 229 kB | 323 kB |
+
+---
+
+## 浏览器使用
+
+```html
+<script src="https://unpkg.com/parse-pinyin@latest/dist/index.global.js"></script>
+<script>
+  console.log(pinyin.toPinyin('中')); // ["zhōng", "zhòng"]
+  console.log(pinyin.toHanzi('xíng')); // ["行", "形", "型", ...]
+</script>
+```
+
+---
+
+## Node.js 使用
+
+```javascript
+const { toPinyin, toHanzi, parse } = require('parse-pinyin');
+
+console.log(toPinyin('中')); // ["zhōng", "zhòng"]
+console.log(toHanzi('xíng')); // ["行", "形", "型", ...]
+console.log(parse('zhōng')); // { shengmu: 'zh', yunmu: 'ong', shengdiao: 1 }
+```
+
+---
+
+## 构建和开发
+
+```bash
+# 安装依赖
+npm install
+
+# 构建项目
+npm run build
+
+# 运行测试
+npm test
+
+# 运行基准测试
+npm run bench
+```
+
+---
+
+## 数据来源
+
+拼音数据来源于 CC-CEDICT 词典，经过预处理和优化以适应高性能查询需求。
+
+---
+
+## 许可证
+
 MIT