进阶专题

扩展程序(实验性)

实验性功能:让独立的小程序跟着你的输入做事,比如按键音。扩展能收到你输入的内容,只启用你信任的

v0.132.0
0.132 新增

实验性功能

扩展程序目前是实验性功能,出厂关闭,只支持 Windows。协议、清单格式和设置界面在后续版本里可能调整,遇到问题请到论坛反馈。

扩展程序能收到你输入的内容

启用后,输入法会按你给的授权,把按键、上屏的文字等输入信息发给扩展程序,其中可能包含聊天内容、账号等隐私。输入法只负责转发,不审查扩展程序的来源和行为,无法保证它们安全——恶意的扩展可能记录或上传你输入的内容。只安装、启用你信任的扩展程序。

扩展程序是独立运行的小程序,由输入法拉起,跟着你的输入做些额外的事,比如打字时播放按键音。它们只能旁观:改不了候选和上屏结果,崩溃、卡住也不影响打字。

目前只支持 Windows。

工作方式

  • 总开关打开后,输入法的服务进程会拉起一个扩展宿主(wind_input_ext),再由宿主启动并看护各个扩展;总开关关着时不启动任何额外进程。
  • 事件是异步、只读地转发的:输入法把按键、上屏等事件放进队列,由宿主投递给扩展。扩展卡住时队列满了就丢事件,不会拖慢打字;扩展也没有任何办法改写候选或上屏结果。
  • 每个扩展只收到你在「设置…」里授权的那几类事件,没授权的不会发。
  • 扩展是你自己装的独立程序,输入法不限制它联网、读写文件。

安装

把扩展的整个文件夹放进用户数据目录下的 extensions\,默认是 %APPDATA%\WindInput\extensions\:

extensions\
  keysound\
    extension.toml
    keysound.exe
    ...

文件夹名就是扩展的 id,删掉文件夹即卸载。设置里「扩展程序目录」那一行有「打开目录」按钮;放好后点「刷新」,列表里就会出现。

启用

在设置 → 高级 → 扩展程序:

  1. 打开「启用扩展程序」总开关。第一次打开会弹出隐私提示,勾选「我已了解上述风险,自行判断扩展程序是否可信」后才能启用,之后不再提示。
  2. 打开扩展那一行自己的开关。
  3. 点底栏「应用设置」。

总开关关着时,各扩展的开关是灰的;「设置…」仍能打开,授权和选项只能看、不能改。

授权

每个扩展在「设置…」里列出它申请的授权,勾上的才会发给它:

授权扩展能收到
按键类别按下的是字母、数字、空格、回车……这一类,不含具体是哪个键
具体按键具体是哪个键、按着哪些修饰键。只是键位,不是打出的字
中英文、全半角与当前方案这几种状态的变化
上屏的文字每次上屏的文字

「上屏的文字」最敏感,等于你打出的全部内容;按键音这类扩展用不到它。首次启用一个扩展时,默认授予它申请的全部项,可以再取消勾选。

输入法会尽量识别密码框,在密码框里只发「按键类别」、不发上屏文字,但不能保证识别所有场景。

事件

扩展能收到的事件有三类:

事件触发需要的授权
按键每次按键按下,英文模式下的按键也会报按键类别,或具体按键
上屏每次有文字上屏上屏的文字
模式中英文、全半角或当前方案变化中英文、全半角与当前方案

上屏事件带一个来源,扩展可以据此区分文字是怎么出来的:

来源含义
candidate选词上屏
punct标点或其他 ASCII 文本
command命令、鼠标点选候选等
softkeyboard鼠标点软键盘的键帽

字段与完整格式见协议文档。

配置文件

设置页改的就是 config.toml 里的 [extensions] 段,一般不用手改:

[extensions]
enabled = true            # 总开关,出厂 false

[[extensions.list]]
id = "keysound"           # 扩展目录名
enabled = true            # 该扩展的开关
granted = ["key.detail"]  # 授予的档位

运行状态

扩展那一行的说明文字就是它当前的状态:

状态说明
运行中正常
未启用扩展自己的开关关着
反复崩溃,已停用一分钟内崩溃三次后不再拉起。关掉再打开这个扩展可以重试
扩展程序无效文件夹里的 extension.toml 写错了,后面跟着原因

扩展自己输出的日志在日志目录(%LOCALAPPDATA%\WindInput\logs\)的 extension-<id>.log。

官方扩展

官方扩展与示例放在 WindInputExtensions 仓库,开源,按键音等官方扩展与协议文档为 MPL-2.0,模板为 MIT:

扩展说明
按键音(keysound)按键时播放音效:键盘、打字机录音音效包,钢琴、木琴合成音色,也可以放自己的音效。只申请「具体按键」

自己写扩展

扩展就是一个读写标准输入输出的程序,任何语言都能写。协议见 WindInputExtensions 仓库的 docs/protocol.md,里面附有 Python 最小示例;仓库的 template/python 是可以直接复制起步的模板。

建议给你分发的扩展签名:未签名的程序收到按键事件,容易被杀毒软件误报。

许可:你的扩展可以闭源

内容许可说明
template/ 扩展模板MIT随便拷、闭源商用都行
协议文档、官方按键音MPL-2.0自己写扩展不受约束;只有修改这些文件本身时,改动那部分要公开
wind-hook 库(输入法仓内的协议 Rust 实现)MPL-2.0同上,Rust 扩展可以直接依赖它

也就是说:按协议写自己的扩展、或从模板起步,扩展本身可以不开源。输入法本体仍是 GPL-3.0。

对这篇文档有疑问,或发现内容有误?

欢迎到文档仓库提 issue,写明问题时附上本页链接即可。

去提 issue →

本页目录