Skip to content

第一个插件 ​

跟着做一个「字数统计」插件:在搜索框输入「字数统计」打开它,或者粘贴一段文字直接统计。整个过程大约十分钟。

包即将发布

文中用到的 @lingtools/plugin-types 等包即将发布到 npm,发布前 pnpm add 会失败。

第 0 步:准备 ​

  1. 安装 lingtools(macOS 13+ 或 Windows 10+),并确认 Node.js ≥ 24、pnpm 可用。
  2. 打开 lingtools 搜索框(默认 Alt + Space),输入「插件市场」,搜索并安装「开发者工具」。

第 1 步:创建工程 ​

bash
pnpm create vite word-count --template vanilla-ts
cd word-count
pnpm install
pnpm add -D @lingtools/plugin-types

@lingtools/plugin-types 只有类型,用来让编辑器认识 window.ling。window.ling 本身由 lingtools 注入,插件不需要打包任何 SDK。

第 2 步:约定目录 ​

插件工程分成两部分:源码在工程根,真正装进 lingtools 的是 src-ling/ 目录。

text
word-count/
├── src/                 页面源码
│   ├── main.ts
│   └── env.d.ts
├── index.html
├── vite.config.ts
├── package.json
└── src-ling/            ← 插件目录:打包时只打这里
    ├── plugin.json
    ├── logo.png
    └── dist/            ← 页面构建产物(vite build 输出到这里)

在 src-ling/ 里放一张正方形图标 logo.png(建议 256×256,也可以用 svg)。

第 3 步:写 plugin.json ​

新建 src-ling/plugin.json:

json
{
  "name": "word-count",
  "title": "字数统计",
  "version": "0.1.0",
  "description": "统计一段文字的字数、行数",
  "main": "dist/index.html",
  "logo": "logo.png",
  "features": [
    {
      "code": "count",
      "explain": "字数统计",
      "cmds": [
        "字数统计",
        "word count",
        { "type": "over", "label": "统计这段文字的字数", "minLength": 2 }
      ]
    }
  ],
  "development": {
    "main": "http://127.0.0.1:5173/"
  }
}

逐项说明:

  • name:插件唯一标识,小写字母、数字和 -。
  • features:一个入口 count。它有三条指令:两条功能指令(用户输入「字数统计」或「word count」时出现),一条匹配指令 over(用户粘贴或输入任意至少 2 个字的文字时,出现在「匹配指令」分组里)。
  • main:打包后的页面入口。
  • development.main:开发时页面从这个地址加载,改代码立即生效。

完整字段见 plugin.json。

第 4 步:配置 Vite ​

替换 vite.config.ts:

ts
import { defineConfig } from 'vite'

export default defineConfig({
  // 插件页面按相对路径加载资源
  base: './',
  build: {
    outDir: 'src-ling/dist',
    emptyOutDir: true,
  },
  server: {
    host: '127.0.0.1',
    port: 5173,
    // 端口必须和 plugin.json 的 development.main 一致,被占用时直接报错
    strictPort: true,
  },
})

第 5 步:写页面 ​

新建 src/env.d.ts,让 TypeScript 认识 window.ling:

ts
/// <reference types="vite/client" />
import type {} from '@lingtools/plugin-types'

替换 index.html 的 <body>:

html
<body>
  <main style="padding: 16px; font-size: 14px; line-height: 1.8">
    <div>字数:<b id="chars">0</b></div>
    <div>行数:<b id="lines">0</b></div>
  </main>
  <script type="module" src="/src/main.ts"></script>
</body>

替换 src/main.ts:

ts
const charsEl = document.querySelector('#chars')!
const linesEl = document.querySelector('#lines')!

function render(text: string) {
  charsEl.textContent = String([...text.replace(/\s/g, '')].length)
  linesEl.textContent = String(text ? text.split('\n').length : 0)
}

// 每次进入插件都会调用:从哪个入口、以什么方式进来
window.ling.onPluginEnter((action) => {
  // 从匹配指令进来时,payload 就是用户粘贴的文字
  const text = action.type === 'over' ? action.payload : ''
  render(text)

  // 把搜索框变成插件自己的输入框,用户继续输入时实时统计
  void window.ling.setSubInput(({ text }) => render(text), '输入或粘贴文字')
  if (text) void window.ling.setSubInputValue(text)
})

第 6 步:装进 lingtools ​

  1. 启动开发服务:

    bash
    pnpm dev
  2. 在 lingtools 搜索框输入「开发者工具」打开它,按 ⌘ N(Windows 为 Ctrl N)新增项目,插件目录选工程根 word-count(会自动改用其中的 src-ling/),保存。

  3. 选中这个项目,按 ⌘ I 安装。插件以开发版 dev-word-count 装进 lingtools。

  4. 回到搜索框输入「字数统计」,回车打开。再试试复制一段文字,粘贴进搜索框,在「匹配指令」分组里选「统计这段文字的字数」。

开发版

开发版的名字带 dev- 前缀,和正式版互不影响,数据也分开存。开发版只在本次运行有效,重启 lingtools 后要在开发者工具里重新安装。

第 7 步:修改与调试 ​

  • 改 src/ 里的代码:Vite 热更新,插件页面即时刷新。
  • 改 plugin.json(加入口、加权限):在开发者工具里选中项目按 ⌘ R 重新加载。
  • 调试方法见 调试与常见问题。

第 8 步:加一个需要权限的功能 ​

给页面加一个「复制结果」按钮。写剪贴板属于敏感能力,要先在 plugin.json 里声明权限:

json
{
  "permissions": ["clipboard.write"]
}
ts
await window.ling.copyText(`字数 ${charsEl.textContent}`)

没有声明就调用,会以错误码 forbidden 失败。声明后按 ⌘ R 重新加载。每个 API 需要什么权限,见 权限。

第 9 步:打包 ​

bash
pnpm build

页面构建到 src-ling/dist/。然后在开发者工具里选中项目按 ⌘ P 打包:确认版本号、选择保存位置,得到 word-count-0.1.0.lpxs。把它拖进 lingtools 搜索框,选「安装插件包」就能以正式版安装。想上架插件市场,见 打包与发布。

下一步 ​