parse-pinyin 1.2.7 → 1.3.0

package/README.md

@@ -1,202 +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 } 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')); 
-// 输出: ["行", "形", "型", ...]
-```
-
-## API 参考
-
-### `toPinyin(char: string, options?: ToneOptions)`
-
-将汉字转换为拼音
-
-#### 参数
-
-- `char`: 要查询的汉字 (单个字符)
-- `options`: 音调选项
-  - `tone`: 是否保留音调 (默认: `true`)
-  - `toneType`: 音调表示方式
-    - `'symbol'`: 声调符号 (默认)
-    - `'number'`: 数字声调
-    - `'array'`: 数组格式 `[拼音, 声调数字]`
-
-#### 返回值
-
-- 带音调符号: `string[]`
-- 数字声调: `string[]`
-- 数组格式: `(string | [string, number])[]`
-
-### `toHanzi(pinyin: string)`
-
-根据拼音查询匹配的汉字
-
-#### 参数
-
-- `pinyin`: 要查询的拼音
-
-#### 返回值
-
-- `string[]`: 匹配的汉字数组
-
-## 使用示例
-
-```javascript
-import { toPinyin, toHanzi } 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('zhong'));
-// 输出: ["中", "忠", "钟", "终", "种", "踵", "盅", "衷", "冢", "柊", ...]
-```
-
-## 性能对比
-
-在典型的使用场景中，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 } = require('parse-pinyin');
-
-console.log(toPinyin('中')); // ["zhōng", "zhòng"]
-console.log(toHanzi('xíng')); // ["行", "形", "型", ...]
-```
-
-## 构建和开发
-
-```bash
-# 安装依赖
-npm install
-
-# 构建项目
-npm run build
-
-# 运行测试
-npm test
-
-# 运行基准测试
-npm run bench
-```
-
-## 数据来源
-
-拼音数据来源于 CC-CEDICT 词典，经过预处理和优化以适应高性能查询需求。
-
-## 许可证
-
-MIT
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request 来改进这个项目！
-```
+# 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

package/dist/index.d.mts

@@ -1,3 +1,15 @@
+type ParsedPinyin = {
+    shengmu: string;
+    yunmu: string;
+    shengdiao: number;
+    yunmuType?: string;
+    zhengtirendu?: string;
+} | null;
+
+/**
+ * 极致优化的拼音查询器 - 从极致优化的TS数据中查询拼音数据
+ */
+
 /**
  * 音调转换选项
  */
@@ -53,8 +65,56 @@ declare class UltraOptimizedPinyinJsonQuery {
      * @returns 匹配的汉字数组
      */
     toHanzi(pinyin: string): string[];
+    /**
+     * 将拼音解析为声母、韵母和声调
+     * @param pinyin 要解析的带音调符号的拼音
+     * @returns 解析后的拼音信息 {shengmu, yunmu, shengdiao} 或者 null
+     */
+    parse(pinyin: string): ParsedPinyin;
+    /**
+     * 检查是否为整体认读音节
+     */
+    private isWholeReading;
+    /**
+     * 提取整体认读音节的声母和韵母
+     */
+    private extractWholeReadingParts;
+    /**
+     * 验证拼音是否有效
+     */
+    private isValidPinyin;
 }
+/**
+ * 导出便捷查询函数
+ */
+/**
+ * 将汉字转换为拼音
+ *
+ * @param char 输入的字符或字符串
+ * @param options 音调选项，用于控制返回拼音的格式
+ * @returns 如果输入是单个汉字，返回其拼音数组；如果输入是字符串，返回一个混合数组（汉字对应的拼音数组 + 非汉字字符）
+ */
 declare const toPinyin: (char: string, options?: ToneOptions) => (string | [string, number])[];
+/**
+ * 根据拼音查询所有匹配的汉字
+ *
+ * @param pinyin 要查询的拼音（可以带声调符号）
+ * @returns 匹配该拼音的所有汉字组成的数组
+ */
 declare const toHanzi: (pinyin: string) => string[];
+/**
+ * 解析拼音为声母、韵母和声调
+ *
+ * @param pinyin 要解析的拼音（可以带声调符号）
+ * @returns 解析结果对象 `{ shengmu: string, yunmu: string, shengdiao: number }` 或 `null`
+ */
+declare const parse: (pinyin: string) => ParsedPinyin;
+/**
+ * 检查输入的字符串是否为有效的拼音
+ *
+ * @param pinyin 要检查的拼音（可以带声调符号）
+ * @returns 如果输入的字符串为有效的拼音，返回 `true`；否则返回 `false`
+ */
+declare const isPinyin: (pinyin: string) => boolean;
 
-export { type ToneOptions, UltraOptimizedPinyinJsonQuery, toHanzi, toPinyin };
+export { type ToneOptions, UltraOptimizedPinyinJsonQuery, isPinyin, parse, toHanzi, toPinyin };

package/dist/index.d.ts

@@ -1,3 +1,15 @@
+type ParsedPinyin = {
+    shengmu: string;
+    yunmu: string;
+    shengdiao: number;
+    yunmuType?: string;
+    zhengtirendu?: string;
+} | null;
+
+/**
+ * 极致优化的拼音查询器 - 从极致优化的TS数据中查询拼音数据
+ */
+
 /**
  * 音调转换选项
  */
@@ -53,8 +65,56 @@ declare class UltraOptimizedPinyinJsonQuery {
      * @returns 匹配的汉字数组
      */
     toHanzi(pinyin: string): string[];
+    /**
+     * 将拼音解析为声母、韵母和声调
+     * @param pinyin 要解析的带音调符号的拼音
+     * @returns 解析后的拼音信息 {shengmu, yunmu, shengdiao} 或者 null
+     */
+    parse(pinyin: string): ParsedPinyin;
+    /**
+     * 检查是否为整体认读音节
+     */
+    private isWholeReading;
+    /**
+     * 提取整体认读音节的声母和韵母
+     */
+    private extractWholeReadingParts;
+    /**
+     * 验证拼音是否有效
+     */
+    private isValidPinyin;
 }
+/**
+ * 导出便捷查询函数
+ */
+/**
+ * 将汉字转换为拼音
+ *
+ * @param char 输入的字符或字符串
+ * @param options 音调选项，用于控制返回拼音的格式
+ * @returns 如果输入是单个汉字，返回其拼音数组；如果输入是字符串，返回一个混合数组（汉字对应的拼音数组 + 非汉字字符）
+ */
 declare const toPinyin: (char: string, options?: ToneOptions) => (string | [string, number])[];
+/**
+ * 根据拼音查询所有匹配的汉字
+ *
+ * @param pinyin 要查询的拼音（可以带声调符号）
+ * @returns 匹配该拼音的所有汉字组成的数组
+ */
 declare const toHanzi: (pinyin: string) => string[];
+/**
+ * 解析拼音为声母、韵母和声调
+ *
+ * @param pinyin 要解析的拼音（可以带声调符号）
+ * @returns 解析结果对象 `{ shengmu: string, yunmu: string, shengdiao: number }` 或 `null`
+ */
+declare const parse: (pinyin: string) => ParsedPinyin;
+/**
+ * 检查输入的字符串是否为有效的拼音
+ *
+ * @param pinyin 要检查的拼音（可以带声调符号）
+ * @returns 如果输入的字符串为有效的拼音，返回 `true`；否则返回 `false`
+ */
+declare const isPinyin: (pinyin: string) => boolean;
 
-export { type ToneOptions, UltraOptimizedPinyinJsonQuery, toHanzi, toPinyin };
+export { type ToneOptions, UltraOptimizedPinyinJsonQuery, isPinyin, parse, toHanzi, toPinyin };