📖 介绍

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>
  */
  

  上述结果浏览器中预览效果如下： 汉 ( hàn ) 语 ( yǔ )

• 更多的 API 请查看pinyin-pro 官网

🏆 竞品对比

以下是 pinyin-pro、pinyin 及 @napi-rs/pinyin 包对于汉字转换的速度及准确率对比，可以看到 pinyin-pro 在各方面都全面领先。

• 准确率测试数据: accuracy
• 性能测试数据：speed

📦 API Size

以下数据由 pnpm size 自动生成。ESM 各 API 为独立打包并开启 Tree Shaking 后的压缩体积；UMD 不支持按 API Tree Shaking，展示完整产物体积。括号内为对应产物 gzip 后的体积。

📠 反馈

使用遇到问题或者需要功能支持欢迎提 issue。

技术交流欢迎加 pinyin-pro 用户群 或者微信：

🧰 Monorepo 开发

本仓库使用 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    # 启动英文文档