跳转至

61 pinyin-拼音输入法

一、概述

pinyin 是 LuatOS 的拼音输入法核心库，用来把「拼音字母串」或「9 键数字序列」查成候选汉字。词库是编译进固件的，不依赖外部文件，也不需要联网。

pinyin 库主要功能：

1、query：传入拼音字符串（如 "zhong"），返回候选字的 Unicode 码点数组，形如 {0x4E2D, 0x949F}；

2、queryUtf8：同样的拼音字符串，直接返回 UTF-8 字符串数组（{"中", "钟"}），不用自己再做码点转 UTF-8，适合直接丢给 lcd、hzfont、airui 显示；

3、querySyllables：传入 9 键输入法的按键序列（如 {8, 3, 5, 5, 3} 对应 z-h-o-n-g），返回这一串按键可能对应的音节列表，按常用度排序。

注意事项：

1、本库编译开关是 LUAT_USE_PINYIN，且只在带 AirUI / PLCUI 界面的固件号里编入；其他固件里 pinyin 是 nil，用前先 if pinyin then 自检；

2、本库只做「拼音 → 候选字」的查表，不是完整的输入法框架：候选词排序、翻页、联想、上屏逻辑都要自己写。词库内部已经把常规字排在前面、多音字排在后面；

3、查不到时返回空表 {} 而不是 nil，所以判断「有没有结果」要用 #codes > 0，不能直接 if codes then；

4、返回的候选字数量不固定，只取前若干个显示时请自己截断，不要假设长度。

二、核心示例

2.1 拼音查候选字并直接显示

local pinyin = require "pinyin"

-- 输入 "zhong"，取 UTF-8 字符数组
local chars = pinyin.queryUtf8("zhong")
log.info("pinyin", "候选字个数", #chars)
for i = 1, math.min(#chars, 10) do
    log.info("pinyin", i, chars[i])
end

2.2 9 键序列取音节，再取候选字

local pinyin = require "pinyin"

-- 按键序列：8=WXYZ，3=GHI，5=MNO，5=MNO，3=GHI
local syllables = pinyin.querySyllables({8, 3, 5, 5, 3})
for i = 1, math.min(#syllables, 5) do
    log.info("pinyin", "音节", syllables[i])
end

-- 取第一个音节对应的候选字
if #syllables > 0 then
    local chars = pinyin.queryUtf8(syllables[1])
    log.info("pinyin", "首选音节", syllables[1], "候选字个数", #chars)
end

三、函数详解

3.1 pinyin.query(pinyin_string)

功能

查询拼音对应的候选字 Unicode 码点数组。

参数

pinyin_string

参数含义：拼音字符串；
数据类型：string；
取值范围：小写拼音字母串，如 "zhong"、"ni"、"hao"；
是否必选：必选；
注意事项：不带声调、不要带空格；传入空字符串直接返回空表；
参数示例："zhong"

返回值

local codes = pinyin.query(pinyin_string)

有一个返回值 codes

codes

含义说明：候选字的 Unicode 码点数组，元素是 number；
         无匹配时返回空表 {}；
数据类型：table；
取值范围：{0x4E2D, 0x949F, ...}；
注意事项：码点不是 UTF-8 字符串，要显示得自己转，或者直接用 pinyin.queryUtf8；

示例

local codes = pinyin.query("zhong")
for i = 1, #codes do
    log.info("pinyin", i, string.format("0x%X", codes[i]))
end

3.2 pinyin.queryUtf8(pinyin_string)

功能

查询拼音对应的候选字，直接返回 UTF-8 字符串数组。

参数

pinyin_string

参数含义：拼音字符串；
数据类型：string；
取值范围：小写拼音字母串，如 "zhong"；
是否必选：必选；
注意事项：与 pinyin.query 的入参完全一致；
参数示例："zhong"

返回值

local chars = pinyin.queryUtf8(pinyin_string)

有一个返回值 chars

chars

含义说明：候选字的 UTF-8 字符串数组，每个元素是一个汉字字符串；
         无匹配时返回空表 {}；
数据类型：table；
取值范围：{"中", "钟", ...}；
注意事项：可以直接拼接到显示缓冲区或直接 log 打印，不需要再做编码转换；

示例

local chars = pinyin.queryUtf8("zhong")
if #chars > 0 then
    log.info("pinyin", "首个候选字", chars[1])
end

3.3 pinyin.querySyllables(key_sequence)

功能

查询 9 键输入法按键序列对应的音节列表，用于「先按键、再选音节、最后选字」的输入流程。

参数

key_sequence

参数含义：按键序列表，每个元素是 1~8 的数字，1=ABC、2=DEF、3=GHI、4=JKL、5=MNO、6=PQRS、7=TUV、8=WXYZ；
数据类型：table；
取值范围：长度 1~5，元素取值 1~8；
是否必选：必选；
注意事项：不是 table、长度为 0、超过 5、或元素超出 1~8 时，直接返回空表；
参数示例：{8, 3, 5, 5, 3}

返回值

local syllables = pinyin.querySyllables(key_sequence)

有一个返回值 syllables

含义说明：可能的音节字符串数组，按常用度排序（常用音节在前）；
         无匹配时返回空表 {}，最多返回 100 个；
数据类型：table；
取值范围：{"zhong", "zong", ...}；
注意事项：用 #syllables 判断是否有结果，不要用 if syllables then；

示例

-- 8=WXYZ, 3=GHI, 5=MNO, 5=MNO, 3=GHI
local syllables = pinyin.querySyllables({8, 3, 5, 5, 3})
for i = 1, #syllables do
    log.info("pinyin", "音节", i, syllables[i])
end

四、产品支持说明

1、本库由编译开关 LUAT_USE_PINYIN 控制，词库随固件一起编译，固件里没有这个开关时 pinyin 为 nil；

2、按当前的固件配置，Air780EPM 这类 4+4 固件没有编入 pinyin；Air780EHM、Air780EHV、Air780EGH、Air8000 等基于 ec718hm 的型号，只在带 AirUI / PLCUI 界面的固件号里编入，例如 Air780EHM 的 14/114、15/115、16/116、17/117、18/118、19/119、21/121、22/122 号固件；Air8101 没有这个库。具体以固件版本页的库清单为准；

3、使用前最直接的确认方式：在目标固件里跑 log.info("pinyin", pinyin)，打印出 table 说明库在，打印 nil 说明没编进去；

4、AirUI / PLCUI 界面里的中文输入法用的是同一份词库，做纯 Lua 侧的拼音查询（比如自绘键盘、自定义候选栏）时才需要直接 require "pinyin"。

搜索