pinyin-ruby

根据拼音规则生成带注音的Ruby标签的拼音工具（支持 HTML 输出）

安装

npm install pinyin-ruby

或使用 pnpm：

pnpm add pinyin-ruby

用法

基础用法

import { ruby } from 'pinyin-ruby';

// 生成 HTML ruby 标签（默认）
ruby('中文');
// 输出: <ruby>中<rt>zhōng</rt></ruby><ruby>文<rt>wén</rt></ruby>

// 生成纯文本格式
ruby('中文', { format: 'text' });
// 输出: 中(zhōng)文(wén)

// 生成 XML 格式
ruby('中文', { format: 'xml' });
// 输出: <ruby><base>中</base><rt>zhōng</rt></ruby><ruby><base>文</base><rt>wén</rt></ruby>

自定义拼音风格

// 不带声调
ruby('中文', { style: 'normal' });
// 输出: <ruby>中<rt>zhong</rt></ruby><ruby>文<rt>wen</rt></ruby>

// 用数字标注声调
ruby('中文', { style: 'tone2' });
// 输出: <ruby>中<rt>zho1ng</rt></ruby><ruby>文<rt>we2n</rt></ruby>

// 只获取首字母
ruby('中文', { style: 'initials' });
// 输出: <ruby>中<rt>zh</rt></ruby><ruby>文<rt>w</rt></ruby>

// 只获取首字母（小写）
ruby('中文', { style: 'first_letter' });
// 输出: <ruby>中<rt>z</rt></ruby><ruby>文<rt>w</rt></ruby>

处理非中文字符

// 默认跳过非中文字符
ruby('hello中文world');
// 输出: <ruby>中<rt>zhōng</rt></ruby><ruby>文<rt>wén</rt></ruby>

// 保留非中文字符
ruby('hello中文world', { skipNonChinese: false });
// 输出: hello<ruby>中<rt>zhōng</rt></ruby><ruby>文<rt>wén</rt></ruby>world

处理多音字

// 默认只返回第一个拼音
ruby('行走', { format: 'text' });
// 输出: 行(xíng)走(zǒu)

// 返回所有拼音（用顿号分隔）
rubyHeteonym('行走', { format: 'text' });
// 输出: 行(xíng、háng)走(zǒu)

获取详细信息

import { rubyDetails } from 'pinyin-ruby';

const details = rubyDetails('中文');
// 返回:
// [
//   {
//     char: '中',
//     pinyin: 'zhōng',
//     isChinese: true,
//     html: '<ruby>中<rt>zhōng</rt></ruby>',
//     xml: '<ruby><base>中</base><rt>zhōng</rt></ruby>',
//     text: '中(zhōng)'
//   },
//   {
//     char: '文',
//     pinyin: 'wén',
//     isChinese: true,
//     html: '<ruby>文<rt>wén</rt></ruby>',
//     xml: '<ruby><base>文</base><rt>wén</rt></ruby>',
//     text: '文(wén)'
//   }
// ]

API 文档

ruby(text, options?): string

将文本转换为带注音的 Ruby 标签。

参数：

• text - 输入的文本
• options - 配置选项
  • format?: 'html' | 'xml' | 'text' - Ruby 标签的格式（默认：'html'）
  • style?: string - 拼音风格（详见 pinyin 文档）
  • heteronym?: boolean - 是否返回多音字
  • skipNonChinese?: boolean - 是否跳过非中文字符（默认：true）
  • 其他选项参考 pinyin 库

返回值：

• 转换后的 Ruby 标签字符串

rubyDetails(text, options?): RubyItem[]

获取文本的详细拼音和 Ruby 标签信息。

参数：

• text - 输入的文本
• options - 配置选项

返回值：

• Ruby 标签详细信息数组，每项包含：
  • char - 原始字符
  • pinyin - 拼音
  • isChinese - 是否是中文字符
  • html - HTML 格式的 Ruby 标签
  • xml - XML 格式的 Ruby 标签
  • text - 纯文本格式

rubyHeteonym(text, options?): string

生成支持多拼音的 Ruby 标签（多音字用顿号分隔）。

参数：

• text - 输入的文本
• options - 配置选项

返回值：

• 支持多拼音的 Ruby 标签字符串

拼音风格对照表

| 风格 | 输入 | 输出示例 | 说明 | |------|------|---------|------| | tone | 中 | zhōng | 带声调（默认） | | tone2 | 中 | zho1ng | 声调用数字标注在拼音中间 | | to3ne | 中 | zho3ng | 声调用数字标注在拼音末尾 | | normal | 中 | zhong | 不带声调 | | initials | 中 | ZH | 声母（大写） | | first_letter | 中 | Z | 首字母（大写） | | passport | 中 | ZHONG | 护照拼音（大写，无声调） |

应用场景

• 教学工具：为汉字添加拼音注音，辅助儿童和外国学习者学习汉语
• 文本处理：批量为文档添加拼音
• Web 应用：在网页上显示带拼音的汉字
• 电子书：为电子书内容添加拼音注音
• 辅助阅读：为生僻字和难字添加拼音辅助阅读

与拼音库的关系

pinyin-ruby 是基于 pinyin 库的扩展，提供了更便捷的 Ruby 标签生成功能。

License

MIT