子输入框
插件打开后,顶栏上的搜索框可以变成插件自己的输入框。用户不用把手从键盘上挪开,就能继续输入、筛选、选择。
它长什么样
text
┌──────────────────────────────────────────────────────────────────┐
│ [📁 下载] 搜索文件名… [ 扩展名 ] [ 大小 ] [ 按修改时间 ▾ ] │
│ 前缀标签 子输入框 参数框(最多 3 个) 下拉附件 │
├──────────────────────────────────────────────────────────────────┤
│ 插件页面 │
└──────────────────────────────────────────────────────────────────┘
四个部分都由 lingtools 绘制,插件只声明内容、接收变化:
| 部分 | 用途 | API |
|---|---|---|
| 子输入框 | 主要的输入:搜索、筛选、命令 | setSubInput |
| 前缀标签 | 只读的小标签,表示当前范围(如进入的目录) | plugin.setSubInputPrefix |
| 参数框 | 额外的输入项,像 Raycast 的命令参数 | plugin.setSubInputArguments |
| 下拉附件 | 一个下拉选择(排序方式、分类、标签) | plugin.setSubInputAccessory |
子输入框
ts
window.ling.onPluginEnter(() => {
void window.ling.setSubInput(
({ text }) => filter(text), // 用户输入时调用
'搜索便签', // 占位文字
true, // 是否聚焦
)
})- 再次调用
setSubInput会替换回调和占位文字,并清空内容。 setSubInputValue(text)替换内容(同样会触发回调);subInputFocus()、subInputBlur()、subInputSelect()控制焦点与全选;removeSubInput()移除、恢复显示插件标题。- 子输入框在插件页面之外。用户点击插件页面里的按钮时,焦点会离开子输入框;需要保持焦点的按钮可以在
mousedown时preventDefault()。
按键转发
焦点在子输入框里时,下面这些按键会转给插件页面,插件在 document 上监听 keydown 即可,和焦点在页面里时写法一样:
| 按键 | 行为 |
|---|---|
| ↑ ↓ Enter | 转给插件(常用于移动列表选中项、打开选中项) |
| ← → | 先交给插件:插件调用了 preventDefault() 就由插件处理,否则在输入框里移动光标 |
| 带修饰键的组合,如 ⌘ K | 转给插件(编辑用的组合键和 lingtools 自己的快捷键除外) |
转发来的事件 isTrusted 为 false;输入法组合中的按键不会转发。
ts
document.addEventListener('keydown', (event) => {
if (event.key === 'ArrowDown') {
event.preventDefault()
moveSelection(1)
}
})前缀标签
显示在子输入框左边,适合表示「现在在哪」或当前的筛选条件:
ts
await window.ling.plugin.setSubInputPrefix({ label: '下载', icon: 'folder' })
await window.ling.plugin.removeSubInputPrefix()文字最多 64 个字符。必须先有子输入框,否则返回 false。
0.10.0 起标签可以带灰字、缩略图,并且可以让用户移除。比如表示「只看能处理这张图片的结果」:
ts
await window.ling.plugin.setSubInputPrefix(
{ label: '图片', detail: '1920 × 1080', thumbnail: dataUrl, removable: true },
() => clearFilter(), // 用户点了 ×,或在空的子输入框里按了退格
)缩略图只收 PNG、JPEG、WebP 的 data URL,不超过 64 KiB、单边不超过 1024 像素,lingtools 缩到 64 像素显示。图标除 'folder' 外还有 'image'、'file'、'files'、'text'。
参数框
在子输入框和下拉之间加 1–3 个输入框,值由 lingtools 保存:
ts
await window.ling.plugin.setSubInputArguments(
[
{ name: 'from', placeholder: '原文语言' },
{ name: 'to', placeholder: '目标语言', value: 'en' },
],
({ name, values }) => {
// name:刚编辑的参数;values:全部参数的当前值
translate(values.from, values.to)
},
)- Tab / Shift Tab 在子输入框和参数框之间切换;最后一个参数框再按 Tab 把焦点交给插件页面。
- 必填校验由插件自己做:把
invalid: true传进去标红,再用plugin.focusSubInputArgument(name)把焦点移过去。 - 必须先有子输入框;
removeSubInput()时一起移除。
下拉附件
ts
await window.ling.plugin.setSubInputAccessory(
{
type: 'select',
value: 'mtime',
options: [
{ value: 'mtime', label: '按修改时间' },
{ value: 'name', label: '按名称' },
{ value: 'size', label: '按大小' },
],
},
({ value }) => sortBy(value),
)- 最多 200 个选项;选项可以带色点
color(green、blue、orange、red、purple、cyan、yellow、gray),适合表示标签。 searchable: true时弹层顶部有搜索框,lingtools 按选项文字过滤。- 选项超过 200 个(比如全部标签)时,用
searchMode: 'plugin':用户的搜索词交给onSearch,插件查到结果后用plugin.setSubInputAccessoryOptions(options, query)回填。 - 在插件页面里按 ⌘ P(Windows 为 Ctrl P)打开弹层;插件也可以调用
plugin.showSubInputAccessory()。 - 没有子输入框时,下拉显示在插件标题后面。
分离窗口
插件分离到独立窗口后,子输入框、前缀、参数框、下拉会一起带过去,显示在分离窗口的标题栏位置,插件代码不用改。
完整参数见 API 参考 子输入框。