CLINLP【免费下载链接】pinyin:cn: 汉字拼音 ➜ hàn zì pīn yīn项目地址https://gitcode.com/gh_mirrors/pi/pinyin点击查看免费下载导读pinyin是 pinyin 项目中负责「汉字 ➜ 拼音」转换的核心 npm 包v4 版本面向拼音标注、按拼音排序、中文搜索等场景设计。本文以仓库内 v4 API 文档 为骨架结合 核心实现 与 类型声明完整讲解pinyin()函数、全部选项style/mode/segment/heteronym/group/compact、静态属性、CLI 用法以及按拼音排序的实战方案。读完本文你将掌握 v4 版本的完整 API 面并能根据多音字、姓名、分词等场景正确选配参数。一、模块定位与适用环境文档开篇即明确了模块定位Convert Han to pinyin, useful for phonetic notation, sorting, and searching汉字转拼音用于注音、排序和检索。核心特性有三点面向多音字词组的分词支持Segmentation for heteronym words同时支持简体与繁体中文Support Traditional and Simplified Chinese支持多种拼音输出风格Support multiple pinyin style。该模块同时支持Node.js 与 Web 浏览器两种运行环境这一点也体现在打包产物上packages/pinyin/package.json中同时声明了mainCJS、moduleESM与browserUMD三个入口且engines.install-node要求 Node 版本不低于 18。二、安装通过 npm 安装文档给出的标准方式npm install pinyin --save包本身只有commander供 CLI 使用一个运行时依赖分词器node-rs/jieba与segmentit均声明为可选的 peerDependencies见 package.json只有当你需要segment选项使用这两个分词器时才需要额外安装。仓库根目录使用 pnpm workspace 管理在 monorepo 环境中也可以直接以 workspace 方式引用该包。三、快速上手3.1 开发环境TypeScript / ESM文档给出的最基础用法import { pinyin } from pinyin; console.log(pinyin(中心)); // [ [ zhōng ], [ xīn ] ]注意返回结构是二维数组ArrayArraystring外层数组的每个元素对应输入中的一个汉字或一个分词后的词内层数组是该字词的拼音候选列表——默认只取第一个读音因此内层只有一个元素。逐步叠加选项// 开启多音字模式返回一个汉字的全部读音 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 ] ] // 姓名模式优先取姓氏读音 console.log(pinyin(华夫人, { mode: surname })); // [ [huà], [fū], [rén] ]3.2 命令行环境CLI包通过bin字段暴露了pinyin可执行文件$ pinyin 中心 zhōng xīn $ pinyin -h默认情况下 CLI 会把二维结果摊平为空格分隔的一维拼音串输出。四、类型系统详解v4 是 TypeScript 编写的强类型版本所有选项都有明确的类型定义定义见 declare.ts 并通过 包入口 对外导出IPinyinOptions、IPinyinStyle、IPinyinSegment等类型。4.1 IPinyinOptionspinyin()方法的第二个参数类型export interface IPinyinOptions { style?: IPinyinStyle; // output style of pinyin. mode?: IPinyinMode, // mode of pinyin. segment?: IPinyinSegment | boolean; heteronym?: boolean; group?: boolean; compact?: boolean; }内部强类型IPinyinAllOptions见 declare.ts则把每个字段收敛为唯一合法值其中compact的语义注释给出了直观示例compactfalse默认[[nǐ], [hǎo,hào], [ma,má,mǎ]]——每个字各自携带多音候选compacttrue输出所有读音的笛卡尔积组合如[nǐ,hǎo,ma]、[nǐ,hǎo,má]、[nǐ,hào,mǎ]等完整序列。4.2 IPinyinStyle拼音输出风格支持字符串小写/大写与数字两种写法数字为兼容旧版本export type IPinyinStyle normal | tone | tone2 | to3ne | initials | first_letter | // 推荐 NORMAL | TONE | TONE2 | TO3NE | INITIALS | FIRST_LETTER | 0 | 1 | 2 | 5 | 3 | 4; // 兼容在 util.ts 中字符串与数字写法通过pinyinStyleMap统一映射为内部枚举normal/0、tone/1、tone2/2、initials/3、first_letter/4、to3ne/5另有 v4 新增的passport/6护照风格见下文静态属性。非法值会回退到默认的TONE。4.3 IPinyinMode转换模式目前支持普通与姓名两种// - NORMAL: Default mode is normal mode. // - SURNAME: surname mode, for chinese surname. export type IPinyinMode normal | surname | NORMAL | SURNAME;4.4 IPinyinSegment分词器指定默认不开启分词false设trueWeb 与 Node 环境统一使用内置的Intl.Segmenterzh-Hans-CN、word 粒度也可显式指定字符串注意文档说明segmentit在 Web 端可用nodejieba与node-rs/jieba为 Node 端实现export type IPinyinSegment Intl.Segmenter | nodejieba | segmentit | node-rs/jieba;五、核心 API5.1Array pinyin(words[, options])将汉字Han转换为拼音options可省略。返回值类型为ArrayArrayString当某个汉字是多音字时其内层数组会包含多个拼音。入口实现在 pinyin.ts 与 PinyinBase.ts内部先调用convertUserOptions合并默认值见 constant.ts 的DEFAULT_OPTIONSstyleTONE、modeNORMAL、heteronymfalse、groupfalse、compactfalse若mode SURNAME走姓名专用流程否则按是否开启segment分流到分词转换segment_pinyin或单字转换normal_pinyin非中文字符数字、字母、标点会原样保留连续的非中文片段作为一个整体输出不参与拼音转换见normal_pinyin的nohans缓存逻辑。5.2Number pinyin.compare(a, b)默认的拼音比较实现可直接传给Array.prototype.sort做拼音排序。底层实现PinyinBase.ts是把两个入参分别用STYLE_TONE2风格转成拼音后对字符串结果做localeCompare。5.3pinyin.compact(arr)将二维数组按多音字候选做笛卡尔积组合见 util.ts是options.compact的底层实现也可作为独立工具函数使用。六、选项逐项解析6.1options.segment分词开关默认false。开启后会对输入文本先行分词再按词注音。文档明确提示分词有助于修复多音字误读但性能更慢需要更多 CPU 与内存。从实现看分词路径调用this.segment(hans, options.segment)segment.ts四种分词器按优先级依次尝试node-rs/jiebaRust 实现的 jieba首次调用时执行load()加载词典之后用cut(hans, false)切词segmentitNode 端纯 JS 分词使用useDefault(new Segment())默认词典simple: true输出纯词串Intl.Segmenter基于Intl.Segmenter(zh-Hans-CN, { granularity: word })无第三方依赖Web/Node 通用nodejieba兜底默认C 实现的 jieba调用cutSmall(hans, 4)。若指定分词器未安装peerDependencies 缺失会打印提示并退化为整串原样返回异常时也会catch后原样返回。6.2options.heteronym多音字开关默认false。开启后返回该字的全部读音。底层实现在single_pinyinPinyinBase.ts从字表DICT_ZI中取出以逗号分隔的读音数组逐一按目标风格转换若转换为非注音风格如 initials后出现重复会通过缓存去重。测试用例test/test.ts验证了「中」在heteronym下输出[zhōng, zhòng]。6.3options.group词组分组与segment配合使用按分词结果把拼音合并到词组级。例如「我喜欢你」分到词后输出[ [wǒ], [xǐhuān], [nǐ] ]——xǐhuān成为整体。实现上调用groupPhrasesPinyinBase.ts底层由comboutil.ts对多音字候选做组合拼接。该选项单独使用没有意义文档示例中均与segment: true搭配。6.4options.style拼音风格指定输出风格文档建议使用STYLE_*静态属性默认.STYLE_TONE。实际转换逻辑集中在 format.ts 的toFixed()函数声调符号与数字的映射表PHONETIC_SYMBOL见 constant.ts把ā→a1、á→a2等一一对应NORMAL通过正则去掉声调符号只留字母TONE2把声调转为拼音末尾的数字TO3NE把声调数字放在韵母首字母后如li2ngINITIALS从声母表INITIALS见 constant.ts中匹配开头声母无声母的汉字如「爱」「我」返回空字符串这一点文档已特别提示FIRST_LETTER只取首字母若首字母是带调字符则先映射回字母PASSPORT先归一为无调字母再处理ülü/nü → LYU/NYUlüe/nüe → LUE/NUE最后整体大写测试用例见 test/test.ts 中「吕→LYU」「略→LUE」。6.5options.mode转换模式默认pinyin.MODE_NORMAL。姓名场景建议使用pinyin.MODE_SURNAME。源码中SURNAME模式走独立的surname_pinyin流程PinyinBase.ts先检测复姓如「欧阳」查compound_surname数据表命中则整体注音并跳过这两个字符剩余部分按单姓逐个处理查SurnamePinyinData优先取姓氏读音未收录的字回落到single_pinyin例如「华夫人」姓氏「华」取huà而非通用的huá输出[ [huà], [fū], [rén] ]。七、静态属性速查7.1 风格属性pinyin.STYLE_*属性含义示例STYLE_NORMAL普通风格无调pin yinSTYLE_TONE标准声调默认pīn yīnSTYLE_TONE2拼音后附数字调号[0-4]pin1 yin1STYLE_TO3NE声调数字置于韵母首字符后pin1 yin1STYLE_INITIALS仅取声母无声母汉字输出空串中国→zh gSTYLE_FIRST_LETTER仅保留首字母p ySTYLE_PASSPORT护照风格大写ü输出为YULÜ→LYUv4 新增见 constant.ts这些静态属性同时以实例属性形式挂在类上PinyinBase.ts与函数属性形式挂在导出的pinyin函数上PinyinBase.ts兼容 v2.x 的访问习惯。7.2 模式属性pinyin.MODE_*属性含义MODE_NORMAL普通模式默认MODE_SURNAME姓名模式优先取姓氏读音八、实战按拼音排序文档 QA 给出了两种方案。方案一直接使用内置compareconst pinyin require(pinyin); const data 我要排序.split(); const sortedData data.sort(pinyin.compare);方案二自定义排序先持久化拼音结果const pinyin require(pinyin); const data 我要排序.split(); // 建议将拼音结果持久化避免重复计算。 const pinyinData data.map(han ({ han: han, pinyin: pinyin(han)[0][0], // 按需选择 options 与 style。 })); const sortedData pinyinData.sort((a, b) { return a.pinyin.localeCompare(b.pinyin); }).map(d d.han);compare底层已内置STYLE_TONE2localeComparePinyinBase.ts因此方案一可直接排序方案二适合需要自定义风格如按无调拼音排序或需要缓存结果的场景。九、测试与验证仓库在 test/test.ts 中覆盖了各风格的完整用例矩阵单音字如「我」、多音字如「中」「啊」、元音字如「爱」、ü系汉字「吕」「略」「虐」等均逐一断言STYLE_NORMAL / PASSPORT / TONE / TONE2 / TO3NE / INITIALS / FIRST_LETTER七种输出。运行测试npm test对应jest --coverage见 package.json。另外 segment 测试 与 format 测试 可分别验证分词与风格转换边界。十、QA 补充Q1多音字模式返回的读音顺序是什么顺序即字表DICT_ZIdata/dict-zi.ts中的记录顺序开启分词后命中的词组会优先查 词组拼音数据 的固定注音从而把多音字固化为语境下的正确读音。Q2非中文内容如何处理非中文字符不会被转拼音而是原样输出连续的非中文片段会合并为单个数组元素见normal_pinyin的nohans逻辑。Q3模块同时支持 Node 与浏览器吗是。文档明确说明 This module both support Node and Web browserWeb 端入口为 pinyin-web.ts浏览器版分词默认走Intl.SegmenterNode 端入口为 pinyin.ts。赞分享CLINLP【免费下载链接】pinyin:cn: 汉字拼音 ➜ hàn zì pīn yīn项目地址https://gitcode.com/gh_mirrors/pi/pinyin点击查看免费下载相关推荐使用 Wio Terminal 通过 MQTT 连接公共代理夜灯物联网设备的网络接入实战IoT-For-Beginners 第 4 课使用 Wio Terminal 通过 MQTT 连接公共代理夜灯物联网设备的网络接入实战IoT For Beginners 第 4 课 本文是基于微软开源CLINLPGhost-Downloader-3终极指南AI智能下载器如何让你告别龟速下载Ghost Downloader 3终极指南AI智能下载器如何让你告别龟速下载 你是否厌倦了下载大文件时漫长的等待是否希望有一款真正智能的下载工具能够自动优桌面应用网络Phinger Cursors深度解析为什么这是最工程化的光标主题Phinger Cursors深度解析为什么这是最工程化的光标主题 Phinger Cursors是一款被誉为最工程化的光标主题它通过精心设计的图标系上一篇终极指南如何在Unreal Engine中快速安装和使用UEGitPlugin下一篇企业级告警治理平台选型指南3大核心价值与完整实施路径创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考