第一个插件
跟着做一个「字数统计」插件:在搜索框输入「字数统计」打开它,或者粘贴一段文字直接统计。整个过程大约十分钟。
包即将发布
文中用到的 @lingtools/plugin-types 等包即将发布到 npm,发布前 pnpm add 会失败。
第 0 步:准备
- 安装 lingtools(macOS 13+ 或 Windows 10+),并确认 Node.js ≥ 24、pnpm 可用。
- 打开 lingtools 搜索框(默认 Alt + Space),输入「插件市场」,搜索并安装「开发者工具」。
第 1 步:创建工程
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/ 目录。
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:
{
"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:
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:
/// <reference types="vite/client" />
import type {} from '@lingtools/plugin-types'替换 index.html 的 <body>:
<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:
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
启动开发服务:
bashpnpm dev在 lingtools 搜索框输入「开发者工具」打开它,按 ⌘ N(Windows 为 Ctrl N)新增项目,插件目录选工程根
word-count(会自动改用其中的src-ling/),保存。选中这个项目,按 ⌘ I 安装。插件以开发版
dev-word-count装进 lingtools。回到搜索框输入「字数统计」,回车打开。再试试复制一段文字,粘贴进搜索框,在「匹配指令」分组里选「统计这段文字的字数」。
开发版
开发版的名字带 dev- 前缀,和正式版互不影响,数据也分开存。开发版只在本次运行有效,重启 lingtools 后要在开发者工具里重新安装。
第 7 步:修改与调试
- 改
src/里的代码:Vite 热更新,插件页面即时刷新。 - 改
plugin.json(加入口、加权限):在开发者工具里选中项目按 ⌘ R 重新加载。 - 调试方法见 调试与常见问题。
第 8 步:加一个需要权限的功能
给页面加一个「复制结果」按钮。写剪贴板属于敏感能力,要先在 plugin.json 里声明权限:
{
"permissions": ["clipboard.write"]
}await window.ling.copyText(`字数 ${charsEl.textContent}`)没有声明就调用,会以错误码 forbidden 失败。声明后按 ⌘ R 重新加载。每个 API 需要什么权限,见 权限。
第 9 步:打包
pnpm build页面构建到 src-ling/dist/。然后在开发者工具里选中项目按 ⌘ P 打包:确认版本号、选择保存位置,得到 word-count-0.1.0.lpxs。把它拖进 lingtools 搜索框,选「安装插件包」就能以正式版安装。想上架插件市场,见 打包与发布。