与宿主一致的界面
lingtools 自己的界面用 Vue 3 + Element Plus(Arco 风格)写成。插件用同一套组件和主题,看起来就像 lingtools 的一部分,并自动跟随亮暗色和毛玻璃。
这一页是推荐做法,不是强制要求:插件页面就是普通网页,用什么框架都可以。
工程配置
在 第一个插件 的基础上,换成 Vue 工程:
pnpm create vite my-plugin --template vue-ts
cd my-plugin
pnpm add vue element-plus @vueuse/core
pnpm add -D @lingtools/plugin-types @lingtools/plugin-sdk @lingtools/ui unocssvite.config.ts:
import { defineConfig } from 'vite'
import { lingVitePlugins } from '@lingtools/ui/vite'
export default defineConfig({
base: './',
// Vue、Element Plus 按需导入(含 Arco 主题)、UnoCSS
plugins: lingVitePlugins(),
build: { outDir: 'src-ling/dist', emptyOutDir: true },
server: { host: '127.0.0.1', port: 5173, strictPort: true },
})lingVitePlugins() 会加载 UnoCSS,工程根需要一个 uno.config.ts:
import { defineConfig, presetWind3 } from 'unocss'
export default defineConfig({
presets: [presetWind3()],
})有了它,Element Plus 的组件(<el-button>、<el-input>……)和 ElMessage 等 API 都不用手动导入。
跟随主题
src/main.ts:
import { createApp } from 'vue'
import { useTheme } from '@lingtools/ui'
// 亮暗色变量、Element Plus 的 Arco 风格、毛玻璃样式,入口引入一次
import '@lingtools/ui/theme'
// ElMessage / ElMessageBox 是 API 调用,样式要显式引入
import 'element-plus/theme-chalk/el-message.css'
import 'element-plus/theme-chalk/el-message-box.css'
import 'virtual:uno.css'
import App from './App.vue'
const { themeReady } = useTheme({
kind: 'plugin',
source: {
read: () => window.ling.getTheme(),
subscribe: (callback) => window.ling.onThemeChange(callback),
},
})
// 等主题就绪再挂载,避免先闪一帧亮色
themeReady
.catch((error) => console.error('读取主题失败:', error))
.finally(() => createApp(App).mount('#app'))同时在 plugin.json 里打开透明背景,让页面透出 lingtools 的卡片底色与毛玻璃:
{ "view": { "appStyle": true } }组件里需要知道当前主题时,用 useCurrentTheme() / useCurrentGlass()。
常用组件
底栏:LingFooter
lingtools 的页面底部都有一条 40 像素高的底栏:左边是提示,右边是带快捷键的操作。
<script setup lang="ts">
import { LingFooter, LingFooterDivider, LingShortcutButton } from '@lingtools/ui'
</script>
<template>
<LingFooter>
<template #start>共 12 条</template>
<LingShortcutButton :keys="['↵']" @click="open">打开</LingShortcutButton>
<LingFooterDivider />
<LingShortcutButton :keys="['⌘', 'K']" @click="showActions">操作</LingShortcutButton>
</LingFooter>
</template>键帽文字可以用 @lingtools/plugin-sdk 的 acceleratorKeycaps('Mod+KeyK', currentPlatform) 生成,macOS 显示 ⌘K、Windows 显示 Ctrl K。单独显示键帽用 LingKeycaps。
操作面板:LingActionPanel
按 ⌘ K 弹出的操作列表,与 lingtools 搜索框里的操作面板外观一致:标题、分组的操作行、底部搜索。用 filterActionPanelItems 实现搜索过滤,单行用 LingActionItem。
列表选中:useListSelection
启动器风格的列表:有一个「当前行」,↑↓ 移动,列表变化时尽量保持选中,接近末尾时加载下一页。
import { useListSelection, LIST_KEY_ATTRIBUTE } from '@lingtools/ui'
const listEl = ref<HTMLElement | null>(null)
const { current, selectedKey, select, move } = useListSelection({
items: () => notes.value,
keyOf: (note) => note._id,
listElement: listEl,
onNearEnd: loadMore,
})
document.addEventListener('keydown', (event) => {
if (event.key === 'ArrowDown') { event.preventDefault(); move(1) }
if (event.key === 'ArrowUp') { event.preventDefault(); move(-1) }
if (event.key === 'Enter' && current.value) open(current.value)
})每一行元素要带 data-list-key 属性(常量 LIST_KEY_ATTRIBUTE),值为行标识,滚动定位靠它。
界面习惯
照着这些做,插件用起来会和 lingtools 一样顺手:
- 键盘优先:列表用 ↑↓ 移动、Enter 打开;常用操作给快捷键,并在底栏或操作面板里显示键帽。
- 鼠标移上去即选中,单击打开;列表行用
@mousedown.prevent,不抢走子输入框的焦点。 - 按键在
document上监听,处理过的调用event.preventDefault();页面上有对话框打开时(hasOpenModalDialog())不处理全局按键。 - 控件优先用 Element Plus 默认样式,不要为了好看大量覆盖。
- 空状态用
el-empty,给一个和插件相关的图标与一句说明。 - 确认操作用
ElMessageBox。 - 不占用 ⌘ /(插件菜单)和 ⌘ P(有下拉附件时打开下拉)。