LimePinyin 汉字转拼音组件

一个全端通用的中文转拼音 UTS 库，轻量高效。支持多种拼音格式输出，包括带音调、不带音调、数字音调等多种形式，可用于中文排序、搜索、输入法等多种应用场景。组件提供了丰富的自定义选项，可以满足各种复杂的拼音转换需求。

文档链接

📚 组件详细文档请访问以下站点：

• 汉字转拼音组件文档 - 站点1
• 汉字转拼音组件文档 - 站点2
• 汉字转拼音组件文档 - 站点3

安装方法

1. 在uni-app 中搜索并导入lime-pinyin
2. 导入后在页面引入相关方法
3. App端需要自定义基座才能使用

注意事项 由于内部用到了getFileSystemManager，App打包时如果没有在页面使用到getFileSystemManager会报错。 建议在任意页面添加以下代码：

const manager = uni.getFileSystemManager();

代码演示

基础拼音转换

通过不同的选项参数，可以获得多种格式的拼音结果：

import { pinyin, type CompleteOptions } from '@/uni_modules/lime-pinyin'

// 获取带音调拼音
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'

// 获取不带声调的拼音
pinyin('汉语拼音', { toneType: 'none' } as CompleteOptions); // 'han yu pin yin'

// 获取声调转换为数字后缀的拼音
pinyin('汉语拼音', { toneType: 'num' } as CompleteOptions); // 'han4 yu3 pin1 yin1'

// 获取数组形式带音调拼音
pinyin('汉语拼音', { type: 'array' } as CompleteOptions); // ["hàn", "yǔ", "pīn", "yīn"]

// 获取数组形式不带声调的拼音
pinyin('汉语拼音', { toneType: 'none', type: 'array' } as CompleteOptions); // ["han", "yu", "pin", "yin"]

// 获取数组形式声调转换为数字后缀的拼音
pinyin('汉语拼音', { toneType: 'num', type: 'array' } as CompleteOptions); // ["han4", "yu3", "pin1", "yin1"]

获取声母

设置 options.pattern 为 initial 时，返回拼音的声母：

import { pinyin, type CompleteOptions } from '@/uni_modules/lime-pinyin'

// 获取声母
pinyin('汉语拼音', { pattern: 'initial' } as CompleteOptions); // 'h y p y'

// 获取数组形式声母
pinyin('汉语拼音', { pattern: 'initial', type: 'array' } as CompleteOptions); // ["h", "y", "p", "y"]

获取韵母

设置 options.pattern 为 final 时，返回拼音的韵母：

import { pinyin, type CompleteOptions } from '@/uni_modules/lime-pinyin'

// 获取带音调韵母
pinyin('汉语拼音', { pattern: 'final' } as CompleteOptions); // 'àn ǔ īn īn'

// 获取不带音调韵母
pinyin('汉语拼音', { pattern: 'final', toneType: 'none' } as CompleteOptions); // 'an u in in'

// 获取音调为数字的韵母
pinyin('汉语拼音', { pattern: 'final', toneType: 'num' } as CompleteOptions); // 'an4 u3 in1 in1'

// 获取数组形式带音调韵母
pinyin('汉语拼音', { pattern: 'final', type: 'array' } as CompleteOptions); // ["àn", "ǔ", "īn", "īn"]

获取韵头/韵腹/韵尾

设置 options.pattern 为 finalHead/finalBody/finalTail 时，返回拼音的韵头/韵腹/韵尾：

import { pinyin, type CompleteOptions } from '@/uni_modules/lime-pinyin'

// 返回韵头
pinyin('村庄', { pattern: 'finalHead', type: 'array' } as CompleteOptions); // [ '', 'u' ]

// 返回韵腹
pinyin('村庄', { pattern: 'finalBody', type: 'array' } as CompleteOptions); // [ 'ū', 'ā' ]

// 返回韵尾
pinyin('村庄', { pattern: 'finalTail', type: 'array' } as CompleteOptions); // [ 'n', 'ng' ]

获取音调

设置 options.pattern 为 num 时，返回拼音的音调对应的数字：

import { pinyin, type CompleteOptions } from '@/uni_modules/lime-pinyin'

// 获取音调
pinyin('汉语拼音', { pattern: 'num' } as CompleteOptions); // '4 3 1 1'

// 获取数组形式音调
pinyin('汉语拼音', { pattern: 'num', type: 'array' } as CompleteOptions); // ["4", "3", "1", "1"]

获取首字母

设置 options.pattern 为 first 时，返回拼音的首字母：

import { pinyin, type CompleteOptions } from '@/uni_modules/lime-pinyin'

// 获取拼音首字母
pinyin('赵钱孙李额', { pattern: 'first' } as CompleteOptions); // 'z q s l é'

// 获取不带音调拼音首字母
pinyin('赵钱孙李额', { pattern: 'first', toneType: 'none' } as CompleteOptions); // 'z q s l e'

// 获取数组形式拼音首字母
pinyin('赵钱孙李额', { pattern: 'first', type: 'array' } as CompleteOptions); // ['z', 'q', 's', 'l', 'é']

获取完整内容

设置 options.type 为 all 时，返回拼音的全部内容的数组：

import { pinyin, type CompleteOptions } from '@/uni_modules/lime-pinyin'

const result = pinyin('汉语拼音', { type: 'all' });
// 返回包含完整拼音信息的数组

处理多音字

设置 options.multiple 为 true 时，可以获取多音字的所有拼音：

import { pinyin, type CompleteOptions } from '@/uni_modules/lime-pinyin'

// 获取多音
pinyin('好', { multiple: true } as CompleteOptions); // 'hǎo hào'

// 获取数组形式多音
pinyin('好', { multiple: true, type: 'array' } as CompleteOptions); // ["hǎo", "hào"]

// text 不为单个字符时 multiple 不生效
pinyin('好学', { multiple: true } as CompleteOptions); // hào xué

姓氏模式

设置 options.surname 为 head(只识别字符串开头的姓氏字符) 或者 all(识别字符串全部的姓氏字符) 可以开启姓氏模式：

import { pinyin, type CompleteOptions } from '@/uni_modules/lime-pinyin'

// 不开启姓氏模式
pinyin('我叫曾乐乐'); // 'wǒ jiào céng lè lè'

// 开启 head 姓氏模式
pinyin('我叫曾乐乐', { surname: 'head' } as CompleteOptions); // 'wǒ jiào zēng lè lè'

// 开启 all 姓氏模式（会将"乐"也识别为乐毅的yuè姓氏）
pinyin('我叫曾乐乐', { surname: 'all' } as CompleteOptions); // 'wǒ jiào zēng yuè yuè'

自定义词汇

插件内置了一些高频常用词的词典，想要保证高准确率，需要应用更完备的词典，可以通过 addDict 添加词典。

可以使用pinyin-pro官方提供的词典，但是数据包比较大，不建议直接放在项目里加载，特别是UniAppX App端会直接崩溃。

npm install @pinyin-pro/data
yarn add @pinyin-pro/data
pnpm add @pinyin-pro/data

import { addDict } from '@/uni_modules/lime-pinyin'

// 非App端
import CharsDict from '@pinyin-pro/data/chars'; // 僻字字典
import CompleteDict from '@pinyin-pro/data/complete'; // 中文分词库词语拼音合集
import ModernDict from '@pinyin-pro/data/modern'; // 《现代汉语词典(第 7 版)》词语拼音合集
addDict(json)

// UniAppX App端 - 把词汇复制到static目录，或放在服务器下载到本地再加载
const manager = uni.getFileSystemManager();
manager.readFile({
  filePath: 'static/modern.json',
  encoding: 'utf-8',
  success: (res) => {
    const obj = JSON.parse<UTSJSONObject>(res.data as string)
    if(obj == null) return
    addDict(obj)
  },
} as ReadFileOptions);

快速预览

导入插件后，可以直接使用以下标签查看演示效果：

<!-- 代码位于 uni_modules/lime-pinyin/components/lime-pinyin -->
<lime-pinyin />

插件标签说明

标签名	说明
l-pinyin	组件标签
lime-pinyin	演示标签

API文档

pinyin 函数参数

参数	说明	类型	默认值
text	要转换的中文文本	string	-
options	转换选项	CompleteOptions	{}

CompleteOptions 选项

属性名	说明	类型	默认值
pattern	拼音输出模式	string	'pinyin'
toneType	音调输出类型	'symbol' | 'num' | 'none'	'symbol'
type	返回结果类型	'string' | 'array' | 'all'	'string'
multiple	是否输出多音字的所有拼音	boolean	false
surname	姓氏模式	'head' | 'all' | null	null

pattern 可选值

值	说明
pinyin	完整拼音
initial	声母
final	韵母
finalHead	韵头(介音)
finalBody	韵腹
finalTail	韵尾
first	首字母
num	音调数字

toneType 可选值

值	说明
symbol	带音调符号，如 "hàn"
num	数字音调，如 "han4"
none	不带音调，如 "han"

type 可选值

值	说明
string	返回字符串，如 "hàn yǔ"
array	返回数组，如 ["hàn", "yǔ"]
all	返回包含完整拼音信息的数组

addDict 函数参数

参数	说明	类型
dict	要添加的词典对象	object

功能特点

• 支持多种拼音输出格式（带音调、不带音调、数字音调）
• 支持声母、韵母、韵头、韵腹、韵尾等细粒度拼音组成部分的获取
• 支持多音字处理
• 支持姓氏模式，优先识别百家姓
• 支持自定义词典，提高转换准确率
• 轻量高效，全端通用

常见问题

• App端需要自定义基座才能使用
• 大型词典可能会占用较多内存，建议按需加载
• 多音字在非单字模式下默认只返回一个音，如需获取所有读音，请使用单字 + multiple 模式
• 姓氏模式可能会导致某些词语的拼音不符合常规读音，请根据实际需求选择是否启用

感谢

本插件基于 pinyin-pro 实现，感谢原作者的贡献。

支持与赞赏

如果你觉得本插件解决了你的问题，可以考虑支持作者：

支付宝赞助	微信赞助

源代码

组件源码