Skip to content

依赖的包 ​

写插件只需要 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 生成 DOMpnpm 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-sdkcurrentPlatform 当前平台('macos' / 'windows' / 'linux');matchAccelerator(event, 'Mod+KeyK', currentPlatform) 判断按键是否命中快捷键;acceleratorKeycaps('Mod+KeyK', currentPlatform) 把快捷键转成键帽文字(macOS 用 ⌘⌥⇧ 符号);hasOpenModalDialog() 页面上是否有打开的对话框;ApiCallError / isApiError() 识别 API 错误;createAiTool() 定义 AI 工具
@lingtools/plugin-sdk/vueuseDbStorage(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 许可证与源码可获取的说明;
  • 如果修改了包里的文件再分发,需要公开修改后的那些文件的源码。