pinyin-pro 是一个专业的 js 汉字拼音转换库，功能丰富、准确率高、性能优异。
中文文档 | English Docs | 在线运行
- 支持拼音/声母/韵母/首字母/音调/全部信息
- 支持人名姓氏模式
- 支持文本和拼音匹配
- 支持自定义拼音
- 支持获取带拼音汉字的 HTML 字符串
- 支持获取汉字的所有拼音
- 支持拼音输入转换
- 极致的性能和极高的拼音识别准确率
npm 安装
npm install pinyin-pro浏览器引入
<script src="https://unpkg.com/pinyin-pro"></script>全部功能的使用说明文档请查看在线文档
-
获取拼音，更多功能请查看pinyin API
import { pinyin } from "pinyin-pro"; // 获取字符串格式拼音 pinyin("汉语拼音"); // 'hàn yǔ pīn yīn' // 获取数组格式拼音 pinyin("汉语拼音", { type: "array" }); // ["hàn", "yǔ", "pīn", "yīn"] // 获取不带音调格式拼音 pinyin("汉语拼音", { toneType: "none" }); // "han yu pin yin" // 获取不带音调数组格式拼音 pinyin("汉语拼音", { toneType: "none", type: "array" }); // ["han", "yu", "pin", "yin"] // 音调以数字形式显示 pinyin("汉语拼音", { toneType: "num" }); // "han4 yu3 pin1 yin1" // 自动识别多音字 pinyin("睡着了"); // "shuì zháo le"
-
文本和拼音匹配，更多匹配规则请查看match API
点击展开文本和拼音匹配示例
import { match } from "pinyin-pro"; // 支持首字母匹配 match("中文拼音", "zwp"); // [0, 1, 2] // 支持全拼匹配 match("中文拼音", "zhongwenpin"); // [0, 1, 2] // 支持混合匹配 match("中文拼音", "zhongwp"); // [0, 1, 2]
-
拼音格式转换，更多功能请查看convert API
点击展开拼音格式转换示例
import { convert } from "pinyin-pro"; // 数组转符号 convert("pin1 yin1"); // 'pīn yīn' // 符号转数字 convert("pīn yīn", { format: "symbolToNum" }); // 'pin1 yin1' // 消除符号 convert("pīn yīn", { format: "toneNone" }); // 'pin yin' // 儿化音 convert("dou4 zhi1r") // dòu zhīr convert("dòu zhīr", { format: "symbolToNum" }) // dou4 zhi1r convert("dòu zhīr", { format: "toneNone" }); // 'dou zhir'
-
分词并获取拼音，更多配置请查看segment API
点击展开 segment 基础使用示例
import { segment, OutputFormat } from "pinyin-pro"; // 默认返回分词及对应的拼音 segment("我喜欢学习汉语"); // [ // { origin: "我", result: "wǒ" }, // { origin: "喜欢", result: "xǐhuān" }, // { origin: "学习", result: "xuéxí" }, // { origin: "汉语", result: "hànyǔ" } // ] // 仅获取分词后的拼音 segment("我喜欢学习汉语", { format: OutputFormat.PinyinString }); // "wǒ xǐhuān xuéxí hànyǔ"
-
获取带汉字拼音的 HTML 字符串，更多配置请查看html API
点击展开 HTML 字符串示例
import { html } from "pinyin-pro"; // 带拼音汉字的 HTML 字符串 html("汉语拼音"); /* <span class="py-result-item"> <ruby> <span class="py-chinese-item">汉</span> <rp>(</rp> <rt class="py-pinyin-item">hàn</rt> <rp>)</rp> </ruby> </span> <span class="py-result-item"> <ruby> <span class="py-chinese-item">语</span> <rp>(</rp> <rt class="py-pinyin-item">yǔ</rt> <rp>)</rp> </ruby> </span> */
上述结果浏览器中预览效果如下： 汉 语
-
更多的 API 请查看pinyin-pro 官网
以下是 pinyin-pro、pinyin 及 @napi-rs/pinyin 包对于汉字转换的速度及准确率对比，可以看到 pinyin-pro 在各方面都全面领先。
| 对比项 | pinyin | @napi-rs/pinyin | pinyin-pro | |
|---|---|---|---|---|
| 准确率 | 😕 Node 版: 94.097% | 😕 94.097% | 🤩 99.846% | |
| 😕 Web 版: 91.170% | ||||
| 性能 | 首次使用字典初始化时长 | 🚀 14.261ms | 🐢 160.769ms | 🚀 8.412ms |
| 10k字转换耗时 | 🚲 74.442ms | 🚀 4.298ms | 🚀 7.216ms | |
| 100k字转换耗时 | 🐢 6287.332ms | 🚀 29.32ms | 🚀 45.471ms | |
| 1m字转换耗时 | ⛔ 内存溢出转换失败 | 🚀 297.41ms | 🚀 328.338ms | |
| 10m字转换耗时 | ⛔ 内存溢出转换失败 | 🚀 3907.278ms | 🚀 3375.192ms | |
| 兼容性 | Web 环境 | ✔️ 支持 | ❌ 不支持 | ✔️ 支持 |
| Node 环境 | ✔️ 支持 | ✔️ 支持 | ✔️ 支持 | |
以下数据由 pnpm size 自动生成。ESM 各 API 为独立打包并开启 Tree Shaking 后的压缩体积；UMD 不支持按 API Tree Shaking，展示完整产物体积。括号内为对应产物 gzip 后的体积。
| API | ESM | UMD |
|---|---|---|
| pinyin | 306.40 KB (gzip 134.52 KB) | 316.84 KB (gzip 138.05 KB) |
| segment | 305.14 KB (gzip 133.75 KB) | |
| match | 185.67 KB (gzip 80.90 KB) | |
| convert | 1.78 KB (gzip 0.98 KB) | |
| html | 307.23 KB (gzip 134.83 KB) | |
| polyphonic | 180.75 KB (gzip 78.83 KB) | |
| 总体积 | 559.41 KB (gzip 157.71 KB) |
使用遇到问题或者需要功能支持欢迎提 issue。
技术交流欢迎加 pinyin-pro 用户群 或者微信：
本仓库使用 pnpm workspace 管理以下项目：
packages/pinyin-pro：pinyin-pro核心包packages/data：@pinyin-pro/data扩展字典包及数据处理脚本packages/docs：中英文 VitePress 文档
pnpm install
pnpm build # 构建核心包与数据包
pnpm test # 运行核心包测试
pnpm build:docs # 构建并打包中英文文档
pnpm build:all # 构建全部 workspace
pnpm docs:dev:zh # 启动中文文档
pnpm docs:dev:en # 启动英文文档