Skip to content

搜索卡片 ​

用户输入命中规则时,在搜索结果上方直接显示答案,不用打开插件。入口负责「打开插件」,搜索卡片负责「当场给出答案」。

text
┌ 搜索框:12*3+4 ───────────────────────────────┐
│ ┌ 🧮 计算 ─────────────────────────────────┐ │
│ │  算式  12 × 3 + 4        →     结果  40   │ │  ← 搜索卡片
│ └──────────────────────────────────────────┘ │
│  计算稿纸                       插件          │  ← 普通搜索结果
└───────────────────────────────────────────────┘

用户选中卡片后按 Enter 执行回车动作(如「复制」),按 ⌘ K 看更多动作。卡片右上角有「不再显示」,用户也可以在插件市场里关闭某张卡片。

两种运行方式 ​

原生 native(推荐)webview
代码跑在哪lingtools 内嵌的轻量 JS 引擎隐藏的网页
怎么显示返回数据,lingtools 用固定模板绘制自己往 DOM 里画,也可以返回数据
能用什么ling.*、fetch、定时器、URL、TextEncoder 等常用 Web API;没有 DOM、Intl、localStorage全部 Web API
特点启动快、占用小,卡死会被强制中断想画什么都行

一个插件可以两种混用。两种卡片不共享内存状态,要共享数据就用 ling.db / dbStorage。

第 1 步:声明 ​

json
{
  "extends": {
    "searchCards": [
      {
        "code": "calc",
        "explain": "计算",
        "file": "dist/cards/calc.js",
        "runtime": "native",
        "match": [{ "type": "regex", "match": "/^[\\d\\s+\\-*/().]+$/", "minLength": 3 }],
        "height": 96,
        "timeout": 1000
      }
    ]
  }
}
字段说明
code卡片标识,插件内唯一,不能和入口的 code 重名
explain卡片名称,显示在卡片标题和插件市场里
file卡片文件,一个 ES module,默认导出 createSearchCard(...)
match触发规则,至少一条:regex、img、files、window,字段与匹配指令相同但没有 label;不支持 over
runtimenative 或 webview(默认)
height卡片高度 48–240 像素,默认 120;内容超出时在卡片里滚动
timeoutrun 和动作的超时,1–10000 毫秒,默认 1000
stylewebview 卡片用到的 CSS 文件(native 卡片不能写)
platform可用平台,写法同入口

第 2 步:写卡片文件 ​

ts
export default createSearchCard({
  run(input, ctx) {
    // input.type:'regex' | 'img' | 'files' | 'window'
    // input.payload:与 onPluginEnter 的 payload 相同;regex 时还有 input.match(捕获组)
    const value = evaluate(input.payload)
    if (value === null) return null // 返回 null:这次不出卡片

    return {
      title: String(value),
      view: {
        type: 'conversion',
        from: { label: '算式', value: input.payload },
        to: { label: '结果', value: String(value) },
      },
      enter: { title: '复制', run: () => window.ling.copyText(String(value)) },
      actions: [
        {
          title: '粘贴到前台',
          shortcut: 'Mod+Shift+KeyV',
          run: () => window.ling.hideMainWindowPasteText(String(value)),
        },
      ],
    }
  },
})
  • createSearchCard 是全局函数,由 lingtools 提供,不用导入;类型来自 @lingtools/plugin-types。
  • run 会随用户输入多次调用;输入变化、搜索框隐藏或超时时 ctx.signal 会触发,异步请求要接上它:fetch(url, { signal: ctx.signal })。
  • 抛错、超时、返回的结构不对时不出卡片,只写日志。
  • 动作执行成功后搜索框会隐藏;返回 { keepOpen: true } 可以保持打开(如「刷新汇率」)。动作抛错或超时,用户会看到系统通知。
  • 动作的 shortcut 必须带 Mod、Control 或 Alt,与搜索框已有快捷键冲突时会被忽略。
  • 想在插件里继续(「在 xx 中打开」),在动作里调用 ling.redirectSelf(指令, 内容)。

卡片能调用的 API ​

和插件页面基本相同,权限照常检查。但不能调用作用于插件界面的方法(子输入框、outPlugin、setExpandHeight、创建窗口等),也不能调用 Node 后端。粘贴到前台、redirect、showNotification、显示 / 隐藏搜索框只能在用户触发的动作里调用,run 里调用会被拒绝。

显示:三种模板 ​

返回 view 时,lingtools 用固定模板绘制卡片,颜色、字体跟随主题。根节点只能是下面三种之一:

模板用途结构
text一句答案{ type: 'text', text, subtitle? }
conversion左 → 右:计算、换算、翻译{ type: 'conversion', from: { value, label? }, to: { value, label? } }
rows1–8 行「标签:值」:文件信息、颜色值{ type: 'rows', rows: [{ label, value }] }

值可以是字符串,也可以是带颜色的片段数组:

ts
const value = [
  { text: '12' },
  { text: ' × ', tone: 'secondary' },
  { text: '3' },
]

tone 可选 secondary(次要)、accent(强调)、success(成功)、danger(危险),具体颜色由主题决定。文字原样显示,不会被当成 HTML 或 Markdown。限制:每个值最多 1000 个字、64 个片段,标签最多 50 个字,整个视图最多 64 KiB。

更新显示:需要异步补充内容(如先显示「查询中」再显示结果)时,调用 ctx.update(newView) 用新的完整视图替换,50 毫秒内的多次更新会合并。

用 Vue 写原生卡片 ​

@lingtools/plugin-sdk/vue-card 提供与模板一一对应的组件:Text、Conversion、Side、Rows、Row、Span。响应式数据变化时自动调用 ctx.update。

vue
<!-- src/cards/CalcCard.vue -->
<script setup lang="ts">
import { Conversion, Side, Span } from '@lingtools/plugin-sdk/vue-card'
defineProps<{ expression: string; result: string }>()
</script>

<template>
  <Conversion>
    <Side label="算式">{{ expression }}</Side>
    <Side label="结果"><Span tone="accent">{{ result }}</Span></Side>
  </Conversion>
</template>
ts
// src/cards/calc.ts
import { mountCardView } from '@lingtools/plugin-sdk/vue-card'
import CalcCard from './CalcCard.vue'

export default createSearchCard({
  async run(input, ctx) {
    const result = evaluate(input.payload)
    if (result === null) return null
    return {
      title: result,
      view: await mountCardView(CalcCard, { expression: input.payload, result }, ctx),
      enter: { title: '复制', run: () => window.ling.copyText(result) },
    }
  },
})

卡片要单独构建成一个 ES module,vite.cards.config.ts:

ts
import { defineConfig } from 'vite'
import { lingCardVitePlugins } from '@lingtools/ui/vite'

export default defineConfig({
  plugins: lingCardVitePlugins(),
  build: {
    outDir: 'src-ling/dist/cards',
    emptyOutDir: false,
    target: 'es2022',
    lib: { entry: 'src/cards/calc.ts', formats: ['es'], fileName: () => 'calc.js' },
  },
})

构建命令:vite build -c vite.cards.config.ts。

原生卡片的限制:

  • import 只能用相对路径引用插件包里的 .js / .mjs 文件,所以依赖要打包进卡片文件;
  • 没有 Intl,日期、数字格式化要自己写,或改用 webview 卡片;
  • fetch 只支持 http / https,不带 Cookie,响应最多 10 MiB;
  • 内存上限 32 MB,超时会被强制中断。

webview 卡片 ​

不写 runtime(或写 webview)时,可以在 render 里自己画 DOM:

ts
export default createSearchCard({
  run: (input) => ({ title: describe(input.payload) }),
  render(node, result, ctx) {
    const el = document.createElement('div')
    el.className = 'ling-card-text'
    el.textContent = result.title ?? ''
    node.append(el)
    return () => { /* 清理:移除监听、定时器 */ }
  },
})
  • 没写 render 时,lingtools 用预置样式 .ling-card-text 显示 title;返回了 view 时也由 lingtools 绘制,render 不调用。
  • ctx.state 是这次结果专用的对象,在 run、render 和动作之间共享,比如记录用户在卡片里点中的那一行。
  • 想用 JSX 又不想引入框架,用 @lingtools/jsx。