剪贴板与输入
读写剪贴板、把内容粘贴到用户正在使用的应用、模拟键盘鼠标、拖出文件。
| 能力 | 权限 |
|---|---|
| 写剪贴板、粘贴到前台 | clipboard.write(或 clipboard) |
| 读剪贴板 | clipboard |
| 模拟键鼠、逐字输入 | input |
| 拖出插件目录以外的文件 | fs.read |
剪贴板内容和按键都不会写进日志。
写剪贴板
| 方法 | 说明 |
|---|---|
copyText(text: string, options?: { html?: string }): Promise<boolean> | 写入文字;传 html 时同时写入富文本,富文本应用粘贴出格式、纯文本应用粘贴出 text |
copyImage(image: string | Uint8Array): Promise<boolean> | 写入图片:Data URL、图片字节,或图片文件的绝对路径(PNG、JPEG、GIF、WebP、BMP、TIFF、ICO)。不超过 10 MiB |
copyFile(filePath: string | string[]): Promise<boolean> | 写入文件 / 文件夹(只写路径,粘贴到文件管理器时才复制) |
clipboard.writeHtml(html: string, text: string): Promise<boolean> | 写入 HTML 与纯文本备份 |
读剪贴板
| 方法 | 说明 |
|---|---|
clipboard.readText(): Promise<string> | 读纯文本 |
getCopiedFiles(): Promise<CopiedFile[] | null> | 读剪贴板里的文件 { path, name, isFile, isDirectory }[];没有文件时为 null |
粘贴到前台应用
隐藏搜索框、把焦点还给唤起 lingtools 之前的应用,再模拟 ⌘ V / Ctrl V 粘贴进去。适合片段、翻译、表情这类「选中即输入」的插件。
| 方法 | 说明 |
|---|---|
hideMainWindowPasteText(text, options?: { html? }): Promise<boolean> | 粘贴文字(可带富文本) |
hideMainWindowPasteImage(image): Promise<boolean> | 粘贴图片,参数同 copyImage |
hideMainWindowPasteFile(filePath): Promise<boolean> | 粘贴文件 |
hideMainWindowPasteHtml(html, text): Promise<boolean> | 粘贴富文本 |
hideMainWindowTypeString(text): Promise<boolean> | 不经剪贴板,逐字输入(需要 input 权限) |
- 只对主窗口里的插件有效;在分离窗口里返回
false。 - 粘贴后不会恢复原来的剪贴板内容。
- macOS 需要用户在「系统设置 → 隐私与安全性 → 辅助功能」里允许 lingtools,否则以
permission_denied失败。 - 搭配入口的
mainHide: true,可以做到「搜索框里选中 → 直接粘贴」,用户完全看不到插件界面。
ts
await window.ling.hideMainWindowPasteText(snippet.content)模拟键鼠
需要 input 权限;macOS 需要辅助功能授权。
| 方法 | 说明 |
|---|---|
simulateKeyboardTap(key: string, ...modifiers): Promise<void> | 按下并松开一个键 |
simulateMouseMove(x, y): Promise<void> | 移动鼠标 |
simulateMouseClick(x, y): Promise<void> | 左键单击 |
simulateMouseDoubleClick(x, y): Promise<void> | 左键双击 |
simulateMouseRightClick(x, y): Promise<void> | 右键单击 |
key:单个字符,或entertabspacebackspacedeleteescapeupdownleftrighthomeendpageuppagedownf1–f12(不区分大小写)。modifiers:'shift'、'ctrl'、'alt'、'command'(Windows 上command是 Win 键)。- 鼠标坐标是物理像素,可以用
dipToScreenPoint从页面坐标换算,见 系统与 Shell。
ts
await window.ling.simulateKeyboardTap('v', 'command') // macOS 上的 ⌘V拖出文件
ts
startDrag(filePath: string | string[]): Promise<void>把文件拖出 lingtools(拖到桌面、文件管理器或其他应用)。在 dragstart 事件里先 event.preventDefault() 再调用:
ts
element.addEventListener('dragstart', (event) => {
event.preventDefault()
void window.ling.startDrag(outputPath)
})拖入文件
ts
getPathForFile(file: File): Promise<string | null>用户把文件拖进插件页面时,在 HTML5 drop 事件里拿到的 File 对象上调用,得到文件在磁盘上的绝对路径。拿到路径后,这次运行里插件可以读这个文件(文件夹含其下全部内容),不需要声明 fs.read。
ts
element.addEventListener('drop', async (event) => {
event.preventDefault()
for (const file of event.dataTransfer?.files ?? []) {
const path = await window.ling.getPathForFile(file)
if (path) addFile(path)
}
})