parse-pinyin

一个高效的汉字拼音查询库，总计20900个字，使用极致优化的 JSON 格式存储拼音数据，支持多种输出格式和反向查询功能，并提供拼音解析为声母、韵母和声调的能力。

特性

• 🚀 高性能: 预处理数据结构，查询速度快
• 📦 轻量级: 无外部依赖，包体积小
• 🌐 多格式支持: 支持声调符号、数字声调、数组格式等多种输出
• 🔁 双向查询: 支持汉字查拼音和拼音查汉字
• 🧩 混合输入支持: 支持包含汉字和非汉字字符的字符串处理
• 🔍 拼音解析: 支持将拼音解析为声母、韵母和声调、韵母类型、整体认读类型
• 📱 跨平台: 支持 Node.js、浏览器和 Webpack/Vite 等构建工具
• 🈵 全面覆盖: 覆盖所有汉字，包括生僻字和特殊字（Unicode 范围 0x4E00-0x9FFF）
• 💾 极致压缩: 采用先进的数据压缩技术，20900个汉字数据仅占用极小空间

安装

npm install parse-pinyin

快速开始

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': 数组格式 [拼音, 声调数字]

返回值

• 如果输入是单个汉字，返回其拼音数组。
• 如果输入是字符串，返回一个混合数组（汉字对应的拼音数组 + 非汉字字符）。

示例

// 单个汉字
console.log(toPinyin('中'));
// 输出: ["zhōng", "zhòng"]

// 包含非汉字字符的字符串
console.log(toPinyin('Hello, 世界'));
// 输出: ['H', 'e', 'l', 'l', 'o', ',', ' ', 'shì', 'jiè']

toHanzi(pinyin: string)

根据拼音查询匹配的汉字。

参数

• pinyin: 要查询的拼音（可以带声调符号）

返回值

• string[]: 匹配该拼音的所有汉字组成的数组

示例

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。

示例

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）：

// 测试代码
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 |

浏览器使用

<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 使用

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 }

构建和开发

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 运行基准测试
npm run bench

数据来源

拼音数据来源于 CC-CEDICT 词典，经过预处理和优化以适应高性能查询需求。

许可证

MIT