Skip to content

子输入框 ​

插件打开后,顶栏上的搜索框可以变成插件自己的输入框。用户不用把手从键盘上挪开,就能继续输入、筛选、选择。

它长什么样 ​

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 参考 子输入框。