依赖的包
写插件只需要 window.ling,它由 lingtools 注入。下面四个包都是可选的开发辅助:类型、工具函数、界面组件和卡片运行时。
包即将发布
这四个包即将发布到 npm,发布前 pnpm add 会失败。
一览
| 包 | 什么时候用 | 安装 |
|---|---|---|
@lingtools/plugin-types | 用 TypeScript 写插件(几乎总是需要) | pnpm add -D @lingtools/plugin-types |
@lingtools/plugin-sdk | 需要平台判断、快捷键匹配、Vue 持久化、Vue 写原生搜索卡片、AI 工具辅助 | pnpm add @lingtools/plugin-sdk |
@lingtools/ui | 用 Vue 3 + Element Plus,想让界面与 lingtools 一致 | pnpm add -D @lingtools/ui |
@lingtools/jsx | 写 webview 搜索卡片,想用 JSX 生成 DOM | pnpm add -D @lingtools/jsx |
插件不需要也不应该打包任何「宿主 SDK」:window.ling 在页面加载前就已经注入好了。
@lingtools/plugin-types
只有类型,没有运行时代码:window.ling 的完整类型、plugin.json 的结构(PluginManifest)以及各 API 的数据类型。
在任意一个会被编译的 .d.ts 里写一行,window.ling 就有了类型提示:
ts
// src/env.d.ts
import type {} from '@lingtools/plugin-types'需要具体类型时直接导入:
ts
import type { PluginEnterAction, DbDoc, PluginManifest } from '@lingtools/plugin-types'@lingtools/plugin-sdk
插件页面常用的小工具,按需导入,打包进你的插件。
| 导入 | 内容 |
|---|---|
@lingtools/plugin-sdk | currentPlatform 当前平台('macos' / 'windows' / 'linux');matchAccelerator(event, 'Mod+KeyK', currentPlatform) 判断按键是否命中快捷键;acceleratorKeycaps('Mod+KeyK', currentPlatform) 把快捷键转成键帽文字(macOS 用 ⌘⌥⇧ 符号);hasOpenModalDialog() 页面上是否有打开的对话框;ApiCallError / isApiError() 识别 API 错误;createAiTool() 定义 AI 工具 |
@lingtools/plugin-sdk/vue | useDbStorage(key, initialValue) 把一个 dbStorage 键变成 Vue Ref;useDbCollection(prefix, { parse }) 把一组 ling.db 文档变成响应式列表。详见 数据存储 |
@lingtools/plugin-sdk/vue-card | 用 Vue 写原生搜索卡片:mountCardView 和 Text、Conversion、Side、Rows、Row、Span 组件。详见 搜索卡片 |
示例:
ts
import { currentPlatform, matchAccelerator, isApiError } from '@lingtools/plugin-sdk'
document.addEventListener('keydown', (event) => {
if (matchAccelerator(event, 'Mod+KeyK', currentPlatform)) {
// macOS 上是 ⌘K,Windows 上是 Ctrl+K
}
})
try {
await window.ling.copyText('hi')
} catch (error) {
if (isApiError(error) && error.code === 'forbidden') {
// 没有声明权限,或用户关掉了
}
}/vue 与 /vue-card 需要 vue 3.5+(/vue 另需 @vueuse/core 14+)。
@lingtools/ui
lingtools 自己的界面就是用它写的。包含:
- 主题:
@lingtools/ui/theme样式(Element Plus 的 Arco 风格变量、亮暗色),useTheme()让页面跟随 lingtools 的亮暗色与毛玻璃; - 组件:
LingFooter(底栏)、LingShortcutButton(带快捷键的按钮)、LingKeycaps(键帽)、LingActionPanel(⌘K 操作面板)等; - 组合式函数:
useListSelection()列表的当前行、↑↓ 移动; - Vite 插件:
lingVitePlugins()(Vue、Element Plus 按需导入、UnoCSS)和lingCardVitePlugins()(构建原生搜索卡片)。
需要 vue 3.5+、element-plus 2.14+、@vueuse/core 14+、vite 8+。用法见 与宿主一致的界面。
@lingtools/jsx
webview 搜索卡片用的 JSX 运行时:JSX 直接生成真实 DOM 节点,不依赖任何框架,体积很小。
json
// tsconfig.json
{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "@lingtools/jsx" } }tsx
node.append(<div class="result">{result.title}</div>)原生(native)卡片不用它,改用 @lingtools/plugin-sdk/vue-card。见 搜索卡片。
许可证
四个包都使用 MPL-2.0:
- 直接使用、打包进你的插件都可以,你自己的插件代码不受影响;
- 打包进插件时,请保留 MPL-2.0 许可证与源码可获取的说明;
- 如果修改了包里的文件再分发,需要公开修改后的那些文件的源码。