rime-ice雾凇拼音插件开发指南：Lua API使用详解

rime-ice雾凇拼音插件开发指南：Lua API使用详解

1. 插件开发环境准备

rime-ice雾凇拼音的Lua插件开发需遵循特定的目录结构，所有插件代码均位于项目的lua/目录下。该目录包含多个功能模块，主要包括拼音处理、候选词过滤、计算器功能等核心组件。

主要Lua模块路径：

• 核心插件目录：lua/
• 冷词处理模块：lua/cold_word_drop/
• 计算器插件：lua/calc_translator.lua
• 日期转换插件：lua/date_translator.lua

2. 核心API架构

rime-ice提供的Lua API遵循Rime输入法框架的扩展规范，主要通过以下两种类型的接口实现功能扩展：

2.1 处理器接口（Processor）

处理器接口用于处理用户输入事件，典型应用是快捷键绑定和输入拦截。以冷词处理模块为例：

function processor.init(env)
    local engine = env.engine
    local config = engine.schema.config
    -- 初始化配置和状态
end

function processor.func(key, env)
    local engine = env.engine
    local context = engine.context
    -- 处理按键事件
    return 1 -- kAccept，表示已处理该事件
end

关键API：

• env.engine：获取输入法引擎实例
• context:get_script_text()：获取当前输入编码
• context:refresh_non_confirmed_composition()：刷新候选菜单

2.2 转换器接口（Translator）

转换器接口用于生成候选词，典型应用是自定义输入解析和候选生成。以计算器插件为例：

function calc.func(input, seg, env)
    if not seg:has_tag('calculator') then return end
    -- 解析输入表达式
    local success, result = pcall(load('return ' .. code, 'calculate', 't', calcPlugin))
    if success then
        yield_calc_cand(seg, result, '', express, env.show_prefix)
    end
end

关键API：

• Candidate(type, start, _end, text, comment)：创建候选词对象
• yield(cand)：提交候选词
• seg:has_tag(tag)：检查当前输入段标签

3. 实用功能模块解析

3.1 冷词处理模块

冷词处理模块(lua/cold_word_drop/processor.lua)实现了候选词的隐藏、降频功能，核心实现包括：

1. 初始化流程：

function processor.init(env)
    local _sd, drop_words = pcall(require, "cold_word_drop/drop_words")
    local _sh, hide_words = pcall(require, "cold_word_drop/hide_words")
    env.drop_words = _sd and drop_words or {}
    env.hide_words = _sh and hide_words or {}
    -- 从配置读取快捷键
    env.drop_cand_key = config:get_string("key_binder/drop_cand") or "Control+d"
end

2. 事件处理：

function processor.func(key, env)
    local context = engine.context
    local action_map = {
        [env.drop_cand_key] = "drop",
        [env.reduce_cand_key] = "reduce_freq",
    }
    if context:has_menu() and action_map[key:repr()] then
        local cand = context:get_selected_candidate()
        append_word_to_droplist(env, {word=cand.text, code=preedit_code}, action_type)
        return 1 -- 处理成功
    end
    return 2 -- 不处理，交给下个组件
end

3.2 计算器插件

计算器插件(lua/calc_translator.lua)展示了如何实现自定义输入解析，核心功能包括：

1. 数学函数注册：

local calcPlugin = {
    pi = math.pi,
    sin = math.sin,
    cos = math.cos,
    sqrt = math.sqrt,
    -- 自定义函数
    avg = function(...) 
        local sum = 0
        for _, v in ipairs({...}) do sum = sum + v end
        return sum / select('#', ...)
    end
}

2. 表达式解析与计算：

local success, result = pcall(load('return ' .. code, 'calculate', 't', calcPlugin))
if success and result then
    yield_calc_cand(seg, result, '', express, env.show_prefix)
end

4. 插件配置与集成

4.1 配置文件修改

要启用自定义插件，需修改Rime配置文件(default.yaml)，在对应节点添加配置：

engine:
  processors:
    - lua_processor@cold_word_drop.processor
  translators:
    - lua_translator@calc_translator
  filters:
    - lua_filter@cold_word_drop.filter

4.2 快捷键绑定

在配置文件中添加快捷键定义：

key_binder:
  bindings:
    - { accept: "Control+d", send: "drop_cand" }
    - { accept: "Control+j", send: "reduce_freq_cand" }

5. 开发最佳实践

5.1 错误处理

使用pcall捕获代码执行异常，避免插件崩溃影响整个输入法：

local success, data = pcall(require, "module")
if not success then
    env.log.warning("Failed to load module: " .. data)
    data = {}
end

5.2 性能优化

• 避免在高频调用的func函数中执行复杂计算
• 使用env对象缓存全局状态，减少重复初始化
• 对于大型数据，考虑分块加载

5.3 调试技巧

使用内置日志功能输出调试信息：

env.log.info("Plugin initialized with config: " .. inspect(config))

6. 常用模块参考

模块路径	功能描述	主要接口
lua/date_translator.lua	日期转换	date_translator.func
lua/number_translator.lua	数字转换	number_translator.func
lua/en_spacer.lua	英文空格处理	en_spacer.func
lua/unicode.lua	Unicode转换	unicode_translator.func

7. 插件开发流程总结

1. 创建Lua文件，实现init和func接口
2. 在配置文件中注册插件
3. 测试插件功能，使用日志调试
4. 优化性能和错误处理
5. 提交PR到主仓库(README.md)

通过以上API和示例，开发者可以快速扩展rime-ice的功能，实现个性化的输入体验。更多高级用法可参考现有插件实现或Rime官方文档。