CLINLP【免费下载链接】pinyin:cn: 汉字拼音 ➜ hàn zì pīn yīn项目地址https://gitcode.com/gh_mirrors/pi/pinyin点击查看免费下载本文以 pinyin漢字拼音轉換工具v2 API 文檔為主體完整講解其安裝方式、核心轉換方法、五種拼音風格與兩種拼音模式並結合本倉庫 packages/pinyin 的實際源碼PinyinBase.ts、format.ts、constant.ts剖析底層實現。讀完本文你將掌握如何在 Node 與瀏覽器環境中完成漢字注音、按拼音排序、多音字處理以及姓名場景的姓氏注音。語言版本簡體中文 | English | 繁體中文本文pinyin 是一個將中文字元轉換為拼音的 JavaScript 模組可用於漢字注音、排序、檢索等場景。它同時支持在 Node 服務器端與 Web 瀏覽器端運行。需要說明的是本倉庫當前源碼為 4.x 版本見 packages/pinyin/package.json 中的version: 4.0.0但 4.x 在源碼層面明確保留了對 v2 API 的兼容——在 PinyinBase.ts 中STYLE_*與MODE_*靜態屬性均標註為「兼容 v2.x 中的屬性透出」因此本文介紹的 v2 用法在當前倉庫代碼中依然有效。特性一覽根據詞組智能匹配最正確的拼音依賴分詞算法解決多音字問題。支持多音字heteronym輸出。簡單的繁體支持。支持多種不同拼音風格STYLE_NORMAL、STYLE_TONE、STYLE_TONE2、STYLE_TO3NE、STYLE_INITIALS、STYLE_FIRST_LETTER。安裝通過 npm 安裝 v2 版本npm install pinyin2.0 --save安裝完成後Node 環境中即可通過require(pinyin)引入模組。從當前倉庫源碼看pinyin 包同時提供mainCJS、moduleESM與browserUMD三種入口並在bin字段註冊了pinyin命令行工具見 packages/pinyin/package.json。用法開發者用法var pinyin require(pinyin); console.log(pinyin(中心)); // [ [ zhōng ], [ xīn ] ] console.log(pinyin(中心, { heteronym: true // 啟用多音字模式 })); // [ [ zhōng, zhòng ], [ xīn ] ] console.log(pinyin(中心, { heteronym: true, // 啟用多音字模式 segment: true // 啟用分詞以解決多音字問題。 })); // [ [ zhōng ], [ xīn ] ] console.log(pinyin(我喜歡你, { segment: true, // 啟用分詞 group: true // 啟用詞組 })); // [ [ wǒ ], [ xǐhuān ], [ nǐ ] ] console.log(pinyin(中心, { style: pinyin.STYLE_INITIALS, // 設置拼音風格 heteronym: true })); // [ [ zh ], [ x ] ]從上面的例子可以看到返回值是二維數組第一維的每一項對應輸入字符串中的一個漢字或詞組/非中文片段第二維是該漢字的所有讀音列表。不開啟多音字模式時「中」只返回zhōng開啟後返回zhōng與zhòng兩個讀音。開啟分詞後「中心」被識別為一個詞組從而正確鎖定zhōng這正是「根據詞組智能匹配最正確的拼音」的體現。開啟group: true後「我喜歡你」被按詞組分組為wǒ、xǐhuān、nǐ三段。命令行用法$ pinyin 中心 zhōng xīn $ pinyin -hpinyin命令直接將輸入的漢字轉換為帶聲調拼音pinyin -h可查看命令行工具的完整參數說明。API 詳解Array pinyin(words[, options])將傳入的中文字符串words轉換成拼音字符串數組。options參數是可選的可用於設定拼音風格、開啟多音字選項或啟用分詞。返回二維數組第一維每個數組項的位置對應輸入中文字符串的每個位置第二維是各個漢字的讀音列表——多音字會包含多個拼音項。從源碼看該方法對非字符串輸入做了容錯處理當hans不是字符串時直接返回空數組見 PinyinBase.ts。Number pinyin.compare(a, b)按拼音排序的默認比較算法可直接作為Array.prototype.sort()的回調函數使用。其底層實現是先將兩個漢字分別以STYLE_TONE2數字聲調風格轉換為拼音再對結果進行localeCompare比較見 PinyinBase.ts。該行為在 test.ts 中有對應測試用例驗證我要排序.split()排序後得到排我序要同音節不同聲調馬罵媽麻排序後得到媽麻馬罵說明比較時會將聲調納入排序依據。參數詳解Boolean options.segment是否啟用分詞模式。中文分詞有助於極大降低多音字問題的誤判率但會導致性能明顯下降、內存佔用增加。默認不開啟。從源碼看開啟分詞後轉換流程會從「逐字轉換」切換到「先分詞、再按詞組轉換」的路徑segment_pinyin()將文本切分為詞組長度大於 1 的詞組交給phrases_pinyin()查詢詞組拼音詞典DICT_PHRASES數據見 packages/pinyin/src/data/phrases-dict.ts未命中詞典時再退回逐字轉換見 PinyinBase.ts。補充當前倉庫的 4.x 源碼將segment擴展為可指定具體分詞引擎的字符串支持nodejieba默認C 實現、Intl.Segmenter、segmentit、node-rs/jiebaRust 實現傳入true時使用Intl.Segmenter見 segment.ts 與 util.ts。v2 文檔中的布爾用法仍然兼容。Boolean options.heteronym是否啟用多音字模式默認關閉。關閉多音字模式時每個漢字只返回第一個匹配的拼音如「中心」→[[zhōng], [xīn]]。啟用多音字模式時返回該漢字的所有讀音列表如「中心」→[[zhōng, zhòng], [xīn]]。源碼中單字轉換single_pinyin()會從單字詞典DICT_ZI見 packages/pinyin/src/data/dict-zi.ts讀取以逗號分隔的全部讀音非多音字模式直接取第一個並按目標風格格式化多音字模式則遍歷所有讀音並通過緩存去重——因為不同讀音在轉換為非注音風格後可能產生重複結果見 PinyinBase.ts。Boolean options.group按詞組對拼音進行分組。例如我喜歡你 wǒ xǐhuān nǐ開啟group: true同時需要開啟segment: true後輸出的第一維不再是逐字而是逐詞組。源碼中的groupPhrases()會將詞組內多個字的拼音通過笛卡爾積組合combo見 util.ts例如詞組「朝陽」在開啟多音字時可組合出zhāoyáng與cháoyáng兩種形式——該行為同樣有測試用例覆蓋見 test.ts。Object options.style指定拼音風格通過STYLE_開頭的靜態屬性進行指定默認值為STYLE_TONE帶聲調風格。詳見下文「靜態屬性」一節。options.mode拼音模式默認為pinyin.MODE_NORMAL普通模式。如果你明確處於姓名場景可以使用pinyin.MODE_SURNAME讓姓氏使用更準確的拼音。從源碼看MODE_SURNAME會走獨立的姓名轉換鏈路surname_pinyin()→compound_surname()/single_surname()依次匹配復姓詞典CompoundSurnamePinyinData見 packages/pinyin/src/data/compound_surname.ts與單姓詞典SurnamePinyinData見 packages/pinyin/src/data/surname.ts命中姓氏數據時優先採用姓氏讀音未命中則退回普通單字轉換見 PinyinBase.ts。靜態屬性拼音風格.STYLE_NORMAL普通風格不帶聲調。如pin yin源碼實現將帶聲調字符替換為對應的無聲調字母見 format.ts。.STYLE_TONE聲調風格聲調標注在韻母第一個字母上。注意這是默認風格。如pīn yīn源碼中該風格為toFixed()的默認分支直接返回詞典中的原始帶聲調拼音見 format.ts。.STYLE_TONE2聲調風格 2聲調以數字形式跟在拼音之後用數字 [0-4] 表示。如pin1 yin1源碼通過PHONETIC_SYMBOL映射表ā→a1、á→a2、ǎ→a3、à→a4ü→v0等見 constant.ts將帶聲調字符轉為「字母數字」再把聲調數字移動到拼音末尾見 format.ts。.STYLE_TO3NE聲調風格 3聲調以數字形式標注在注音字符之後用數字 [0-4] 表示。如pi1n yi1n與 TONE2 的區別在於數字的位置TONE2 是pin1數字在整個拼音後TO3NE 是pi1n數字在韻母字母後。源碼直接將帶聲調字符替換為PHONETIC_SYMBOL中的「字母數字」形式即可得到該風格見 format.ts。.STYLE_INITIALS聲母風格只返回各個拼音的聲母部分。對於沒有聲母的漢字返回空字符串。如「中國」的拼音為zh g。注意聲母風格會區分zh和z、ch和c、sh和s。源碼中的聲母表為b,p,m,f,d,t,n,l,g,k,h,j,q,x,r,zh,ch,sh,z,c,s見 constant.tsinitials()函數按表逐一匹配拼音前綴匹配不到則返回空字符串見 format.ts。再次注意部分漢字沒有聲母如「啊」、「餓」等另外y、w、yu都不是聲母這些漢字的聲母風格輸出會是。請仔細考慮你的需求是否應該使用首字母風格。詳情請參考下文〈為什麼沒有 y、w、yu 幾個聲母〉一節。.STYLE_FIRST_LETTER首字母風格只返回拼音的首字母部分。如p y源碼實現取拼音第一個字符若該字符是帶聲調字符如ā則先還原為無聲調字母再取首字母見 format.ts。補充當前倉庫源碼還提供.STYLE_PASSPORT護照風格輸出全大寫拼音且ü按護照規則輸出為YUlüe/nüe特殊處理為LUE/NUE詳見 constant.ts 與 format.ts。此外style參數還支持字符串形式如tone、initials與數字形式如1、3的兼容寫法映射關係見 util.ts。靜態屬性拼音模式.MODE_NORMAL普通模式自動識別讀音。這是默認模式對應源碼中的ENUM_PINYIN_MODE.NORMAL見 constant.ts。.MODE_SURNAME姓名模式對於明確的姓名場景可以更準確地識別姓氏的讀音。例如「單」作為姓氏讀shàn作為普通字讀dān開啟該模式後源碼會優先在 surname.ts 與 compound_surname.ts 兩張姓氏詞典中查詢讀音並能識別「歐陽」「司馬」等復姓場景。底層轉換流程結合源碼可以將一次完整的拼音轉換總結為以下流程見 PinyinBase.ts 的pinyin()入口與normal_pinyin()/segment_pinyin()分支模式判斷若mode為MODE_SURNAME走姓名轉換鏈路否則進入下一步。是否分詞開啟segment時先調用分詞算法將文本切分為詞組再逐詞組轉換未開啟時逐字轉換。單字/詞組查表單字從DICT_ZI查讀音詞組從DICT_PHRASES查讀音未命中的詞組退回逐字處理。風格格式化通過toFixed()見 format.ts將原始帶聲調拼音轉換為目標風格。非中文片段連續的非中文字符作為一個整體原樣輸出不轉換為拼音例如「我愛你 2026」中的空格與數字會被保留在輸出數組中。另外當前倉庫源碼還提供pinyin.compact()方法與compact選項可將多音字的不同組合以「緊湊」形式展開為多個完整句子拼音組合如[[nǐ],[hǎo,hào],[ma]]展開為nǐhǎoma、nǐhǎoma等組合其笛卡爾積實現見 util.ts。測試v2 文檔中執行測試的方式npm test從當前倉庫源碼看pinyin 包的測試由 Jest 驅動packages/pinyin/package.json 中test: jest --coverage測試用例覆蓋了全部風格轉換、多音字、詞組分組、姓名模式與拼音排序比較等場景見 packages/pinyin/test/test.ts可作為驗證本文各示例輸出的權威依據。QA關於 Web 版如何使用首先建議大家優先考慮在服務端一次性轉換拼音並將結果持久化避免在客戶端每次轉換消耗性能、影響體驗。如果你堅持在客戶端使用可以考慮使用 Webpack Babel 將代碼轉換為低端瀏覽器可執行的版本。從源碼看pinyin 包的 UMD 構建browser入口見 packages/pinyin/package.json即面向瀏覽器環境Web 版入口見 packages/pinyin/src/pinyin-web.ts倉庫還提供了經壓縮合併的dict.bin二進制字典數據見 packages/pinyin/src/data/dict.bin以降低網絡傳輸體積。為什麼沒有y、w、yu幾個聲母聲母風格STYLE_INITIALS下「雨」、「我」、「圓」等漢字返回空字符串因為根據《漢語拼音方案》y、w、ü (yu)都不是聲母——在某些特定韻母無聲母時才加上y或w而ü也有其特定規則。這在源碼中有直接體現聲母表INITIALS只包含b,p,m,f,d,t,n,l,g,k,h,j,q,x,r,zh,ch,sh,z,c,s確實不含y、w見 constant.ts而韻母表FINALS中以v表示ü見 constant.ts說明ü被視為韻母而非聲母處理。如果你覺得這帶來了麻煩那麼也要小心一些無聲母的漢字如「啊」、「餓」、「按」、「昂」等。這時候你也許需要的是首字母風格STYLE_FIRST_LETTER。如何實現按拼音排序pinyin 模組提供了默認的排序方案const pinyin require(pinyin); const data 我要排序.split(); const sortedData data.sort(pinyin.compare);如果默認的比較方法不能滿足你的需求可以自定義pinyinCompare方法const pinyin require(pinyin); const data 我要排序.split(); // 建議將漢字的拼音持久化存儲起來。 const pinyinData data.map(han ({ han: han, pinyin: pinyin(han)[0][0], // 可以自行選擇不同的生成拼音方案和風格。 })); const sortedData pinyinData.sort((a, b) { return a.pinyin.localeCompare(b.pinyin); }).map(d d.han);自定義方案的核心思路是先將每個漢字轉為拼音並與原字捆綁再對拼音做localeCompare比較。這樣可以自由選擇拼音風格如不帶聲調的STYLE_NORMAL實現不同粒度的排序需求。Node 版和 Web 版有什麼異同pinyin目前可以同時運行在 Node 服務器端和 Web 瀏覽器端API 和使用方式完全一致。但 Web 版較 Node 版稍簡單拼音庫只有常用字部分沒有使用分詞算法並考慮網絡傳輸對詞庫進行了壓縮處理。由於分詞和繁體中文的特性部分情況下的結果也不盡相同。特性Web 版Node 版拼音庫常用字庫。壓縮、合併完整字庫。不壓縮、合併分詞沒有分詞使用分詞算法多音字拼音更準確。拼音頻度排序有根據拼音使用頻度優先級排序。同 Web 版。繁體中文沒有繁體中文支持。有簡單的繁簡漢字轉換。由於這些區別測試不同運行環境的用例也不盡相同。從源碼結構看Node 版入口 pinyin.ts 額外提供了segment()分詞能力而 Web 版入口 pinyin-web.ts 不帶分詞兩者共享同一套PinyinBase核心邏輯。許可證本項目以 MIT 許可證發佈見倉庫根目錄 LICENSE 與 packages/pinyin/package.json 中的license: MIT。赞分享CLINLP【免费下载链接】pinyin:cn: 汉字拼音 ➜ hàn zì pīn yīn项目地址https://gitcode.com/gh_mirrors/pi/pinyin点击查看免费下载相关推荐pinyin v3 API 完全指南汉字拼音转换、分词、多音字与排序实战pinyin v3 API 完全指南汉字拼音转换、分词、多音字与排序实战 pinyinpīnyīn是汉字拼音转换工具可把中文字符串转换为带声调的拼音数组CLINLPpinyin v4 使用指南汉字转拼音 API 配置、多音字处理与排序实战pinyin v4 使用指南汉字转拼音 API 配置、多音字处理与排序实战 本指南以 pinyin 项目的官方英文文档 apps/website/docs/CLINLPpinyin v4 完整 API 指南汉字拼音转换、多音字处理与分词实战pinyin v4 完整 API 指南汉字拼音转换、多音字处理与分词实战 导读 pinyin 是 pinyin 项目中负责「汉字 ➜ 拼音」转换的核心 npmCLINLP上一篇创意玩法React-Rewards多动画组合与自定义粒子效果下一篇Omarchy录屏质量优化终极指南编码与分辨率设置技巧 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考