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參數將拼音中的ü替換為vtype: "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;
}在瀏覽器中的預覽效果：
出口商品類章金額數據庫)
)
