搜索卡片
用户输入命中规则时,在搜索结果上方直接显示答案,不用打开插件。入口负责「打开插件」,搜索卡片负责「当场给出答案」。
┌ 搜索框: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 步:声明
{
"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 |
runtime | native 或 webview(默认) |
height | 卡片高度 48–240 像素,默认 120;内容超出时在卡片里滚动 |
timeout | run 和动作的超时,1–10000 毫秒,默认 1000 |
style | webview 卡片用到的 CSS 文件(native 卡片不能写) |
platform | 可用平台,写法同入口 |
第 2 步:写卡片文件
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? } } |
rows | 1–8 行「标签:值」:文件信息、颜色值 | { type: 'rows', rows: [{ label, value }] } |
值可以是字符串,也可以是带颜色的片段数组:
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。
<!-- 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>// 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:
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:
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。