Node.js汉字转拼音指南:pinyin-pro全解析
pinyin-pro 工具库简介
- 核心功能:汉字转拼音、多音字处理、音调控制、格式定制等
- 性能特点:高效、轻量级、支持多种拼音风格
- 应用场景:搜索优化、数据排序、中文输入法等
环境准备与安装
- Node.js
- npm 或 yarn 安装 pinyin-pro
npm install pinyin-pro
基础使用示例
以下代码示例展示如何通过 pinyin-pro
库实现多种拼音转换功能:
const { pinyin } = require("pinyin-pro");// 获取带音调拼音
console.log(pinyin("你好世界")); //nǐ hǎo shì jiè// 获取不带音调拼音(toneType默认为symbol)
console.log(pinyin("你好世界", { toneType: "none" })); //ni hao shi jie// 拼音转为数字后缀
console.log(pinyin("你好世界", { toneType: "num" })); //ni3 hao3 shi4 jie4// 获取拼音数组(type默认为string)
console.log(pinyin("你好世界", { type: "array" })); //[ 'nǐ', 'hǎo', 'shì', 'jiè' ] // 获取不带音调拼音数组
console.log(pinyin("你好世界", { toneType: "none", type: "array" }
)); //[ 'ni', 'hao', 'shi', 'jie' ] // 获取数字后缀拼音数组
console.log(pinyin("你好世界", { toneType: "num", type: "array"
})); //[ 'ni3', 'hao3', 'shi4', 'jie4' ]
参数说明
toneType
"symbol"
: 默认值,输出带声调符号的拼音(如nǐ hǎo shì jiè
)"none"
: 输出无声调拼音(如ni hao shi jie
)"num"
: 输出数字后缀形式(如ni3 hao3 shi4 jie4
)
type
"string"
: 默认值,返回拼接后的字符串"array"
: 返回分段拼音数组(如["nǐ", "hǎo", "shì", "jiè"]
)"all"
: 返回拼音完整内容
声母与韵母
// 获取声母
console.log(pinyin("你好世界", { pattern: "initial" }));
//输出:n h sh j// 获取韵母
console.log(pinyin("你好世界", { pattern: "final" }));
//输出:ǐ ǎo ì iè// 获取韵头
console.log(pinyin("光瓜", { pattern: "finalHead", type: "array" }));
//输出:[ 'u', 'u' ]// 获取韵腹
console.log(pinyin("关刀", { pattern: "finalBody", type: "array" }));
//输出:[ 'ā', 'ā' ]// 获取韵尾
console.log(pinyin("大关刀", { pattern: "finalTail", type: "array" }));
//输出:[ '', 'n', 'o' ]// 获取音调
console.log(pinyin("汉语拼音", { pattern: "num", type: "array" }));
//输出:[ '4', '3', '1', '1' ]// 获取拼音首字母
console.log(pinyin("汉语拼音", { pattern: "first", type: "array" }));
//输出:[ 'h', 'y', 'p', 'y' ]
功能说明
- 声母:提取每个汉字拼音的起始辅音部分。
- 韵母:提取每个汉字拼音的元音及后续部分。
- 韵头、韵腹、韵尾:分别拆分韵母的结构,适用于需要分析拼音细节的场景。
- 音调:以数字形式返回拼音的声调(如
4
表示第四声)。 - 拼音首字母:返回每个汉字拼音的首字母(大写形式)。
通过调整 pattern
和 type
参数,可以灵活控制输出格式(字符串或数组)。
完整拼音
// 获取拼音完整内容
console.log(pinyin("汉语拼音", { type: "all" }));
输出结果:
[{origin: '你',pinyin: 'nǐ',initial: 'n',final: 'ǐ',first: 'n',finalHead: '',finalBody: 'ǐ',finalTail: '',num: 3,isZh: true,polyphonic: [ 'nǐ' ],inZhRange: true,result: 'nǐ'},{origin: '好',pinyin: 'hǎo',initial: 'h',final: 'ǎo',first: 'h',finalHead: '',finalBody: 'ǎ',finalTail: 'o',num: 3,isZh: true,polyphonic: [ 'hǎo', 'hào' ],inZhRange: true,result: 'hǎo'}
]
结果参数说明(以“你”为例):
- origin: 汉字本体为“你”
- pinyin: 标准拼音为“nǐ”
- initial: 声母为“n”
- final: 韵母为“ǐ”(单韵母结构)
- 音节拆分:
- first: 首字母“n”
- finalHead: 韵头为空
- finalBody: 韵腹为“ǐ”
- finalTail: 韵尾为空
- 其他属性:
- num: 音调为第三声
- isZh: 属于中文字符
- polyphonic: 无双音,仅“nǐ”一个读音
- inZhRange: 在汉字Unicode范围内
- result: 最终输出拼音“nǐ”
姓名模式
console.log(pinyin("曾乐乐"));
//输出:céng lè lè// 姓氏模式
console.log(pinyin("曾乐乐", { surname: "head" }));
//输出:zēng lè lè// 开启 all 姓氏模式(会将“乐”也识别为乐毅的yuè姓氏)
console.log(pinyin("曾乐乐", { surname: "all" }));
//输出:zēng yuè yuè
代码说明
- 默认模式:仅自动识别首个字符作为文字(如“曾”读 céng)。
head
模式:明确指定首个字符按姓氏处理(与默认行为相同,但显式声明意图)。all
模式:强制将所有可能的姓氏字符按多音字处理(如“乐乐”中的“乐”读yuè
)。
非汉字字符处理
console.log(pinyin("我very喜欢吃"));
// 输出: wǒ v e r y xǐ huan chīconsole.log(pinyin("我very喜欢吃", { nonZh: "removed" }));
// 输出: wǒ xǐ huan chīconsole.log(pinyin("我very喜欢吃", { nonZh: "consecutive" }));
// 输出: wǒ very xǐ huan chī
参数说明
nonZh
参数控制非中文字符的处理方式:
- 默认行为:将每个非中文字符拆分为单独的元素
"removed"
:完全移除所有非中文字符"consecutive"
:将连续的非中文字符合并为一个元素
拼音 ü 替换为 v
console.log(pinyin("吕布"));
//输出 lǚ bùconsole.log(pinyin("吕布", { toneType: "none", v: true }));
//输出 lv bu// 带音调的 ǖ,ǘ,ǚ,ǜ 不转换
console.log(pinyin("吕布", { v: true }));
// lǚ bùconsole.log(pinyin("吕布", { type: "num", v: true }));
//官方文档显示 lv3 bu4
//实际输出 lǚ bù
参数说明
toneType: "none"
参数会移除拼音中的音调标记v: true
参数将拼音中的ü
替换为v
type: "num"
参数会以数字形式标注音调位置
分词
const { segment, addDict, OutputFormat } = require("pinyin-pro");
//完整词典
const CompleteDict = require("@pinyin-pro/data/complete");
//现代汉语词典
const ModernChineseDict = require("@pinyin-pro/data/modern");addDict(CompleteDict); //这里使用完整词典let res1 = segment("小明硕士毕业于中国科学院计算所,后在日本京都大学深造");
res1
是默认输出格式的结果,通常为分词后的数组形式,结果如下:
[{ origin: '小', result: 'xiǎo' },{ origin: '明', result: 'míng' },{ origin: '硕士', result: 'shuòshì' },{ origin: '毕业', result: 'bìyè' },{ origin: '于', result: 'yú' },{ origin: '中国科学院', result: 'zhōngguókēxuéyuàn' },{ origin: '计算所', result: 'jìsuànsuǒ' },{ origin: ',', result: ',' },{ origin: '后', result: 'hòu' },{ origin: '在', result: 'zài' },{ origin: '日本京都大学', result: 'rìběnjīngdūdàxué' },{ origin: '深造', result: 'shēnzào' }
]
分词的不同返回格式
let res2 = segment("小明硕士毕业于中国科学院计算所,后在日本京都大学深造", {format: OutputFormat.AllSegment,
});
format:
- OutputFormat.AllSegment:使用
AllSegment
格式,输出所有可能的分词组合,通常用于语言学研究或需要全面分析的场景。 - OutputFormat.
AllArray
:
将分词结果以数组形式返回 - OutputFormat.
AllString
:
将分词结果以字符串形式返回 - OutputFormat.
PinyinSegment
:
输出分词后的拼音组合 - OutputFormat.
PinyinArray:
将拼音结果以数组形式返回 - OutputFormat.
PinyinString:
将拼音结果以字符串形式返回 - OutputFormat.
ZhSegment:
输出分词后的中文组合 - OutputFormat.
ZhArray:
将中文分词结果以数组形式返回 - OutputFormat.
ZhString:
中文分词结果以字符串形式返回
let res = segment("小明硕士毕业于中国科学院计算所,后在日本京都大学深造", {format: OutputFormat.AllString,separator: "-",
});
使用自定义分隔符 -
,将分词结果以字符串形式返回,适合需要特定分隔符的场景。
拼音汉字匹配
若拼音和文本匹配,返回匹配的文本下标:
import { match } from 'pinyin-pro';match('汉语拼音', 'hanyupinyin'); // [0, 1, 2, 3]
使用 continuous
属性指定匹配的汉字下标是否为连续的才算匹配成功(默认值为 false,即不需要为连续的匹配):
import { match } from 'pinyin-pro';match('汉语拼音', 'hanpin'); // [0, 2]match('汉语拼音', 'hanpin', { continuous: true }); // null
使用 precision
属性可以控制汉字和拼音匹配的精度:
import { match } from 'pinyin-pro';// 默认首字母匹配算匹配成功
match('中文拼音', 'zwpy'); // [0, 1, 2, 3]// every 需要每一个字符都匹配成功
match('中文拼音', 'zwpy', { precision: 'every' }); // null
match('中文拼音', 'zhongwenpinyin', { precision: 'every' }); // [0, 1, 2, 3]// start 只要开头任意个字母匹配就算匹配成功
match('中文拼音', 'zhwpy', { precision: 'start' }); // [0, 1, 2, 3]
match('中文拼音', 'zhwpy'); // null// any 任意有一个字母匹配就算匹配成功
match('中文拼音', 'ongwpy', { precision: 'any' }); // [0, 1, 2, 3]
match('中文拼音', 'ongwpy'); // null
使用 space
属性控制匹配时空格是否不参与匹配:
import { match } from 'pinyin-pro';// 默认不参与匹配
match('汉语拼音', 'han yupinyin'); // [0, 1, 2, 3]match('汉语拼音', 'han yupinyin', { space: 'preserve' }); // null
使用 lastPrecision
属性可以控制最后一个汉字和拼音匹配的精度。默认情况下,precision 为 any
时,lastPrecision 为 any
; 否则 lastPrecision
为 start
。
import { match } from 'pinyin-pro';// 默认情况下
match('汉语拼音', 'hanyupiny'); // [1, 2, 3, 4]// 显式控制 lastPrecision
match('汉语拼音', 'hanyupiny', { lastPrecision: 'every' }); // null
对于多音字,只要其中一个读音匹配上即算匹配成功:
import { match } from 'pinyin-pro';match('会计', 'kuaiji'); // [0, 1]
match('会计', 'huiji'); // [0, 1]
通过指定 v
选项来使用 v
来匹配 ü
:v3.25.0+
import { match } from 'pinyin-pro';match('吕布', 'lvbu'); // [0, 1]
HTML字符串
import { html } from 'pinyin-pro';const htmlString = html('汉语拼音');
//输出html字符串
在浏览器中的预览效果如下:
当设置 toneType
属性的值为 none
时,返回值中的拼音是不带音调的。
import { html } from 'pinyin-pro';const htmlString = html('汉语拼音', { toneType: 'none' });
在浏览器中的预览效果如下:
可以通过 html
api 返回值中的类名来控制具体的样式,如下面的例子中,我们让汉字部分为蓝色,拼音部分为红色。
// js
import { html } from 'pinyin-pro';const htmlString = html('汉语拼音');
/* css */
.py-chinese-item {color: blue;
}
.py-pinyin-item {color: red;
}
在浏览器中的预览效果: