系统与 Shell
打开文件和网址、文件对话框、系统目录、文件图标、读取其他应用、显示器与取色、拼音匹配。
打开与显示
| 方法 | 说明 | 权限 |
|---|---|---|
shellOpenPath(fullPath: string): Promise<string> | 用系统默认方式打开文件或文件夹(可执行文件会被运行) | shell |
shellOpenExternal(url: string): Promise<void> | 用默认程序打开网址或协议链接(https:、mailto: 等);不接受 file: | |
shellShowItemInFolder(fullPath: string): Promise<void> | 在访达 / 资源管理器中显示并选中 | 插件目录外需 fs.read |
shellTrashItem(fullPath: string): Promise<void> | 移到回收站,不经用户确认 | 插件目录外需 fs |
shellBeep(): Promise<void> | 播放系统提示音 |
路径必须是绝对路径;不存在时以 not_found 失败。
文件对话框
不需要权限;用户选中的路径在这次运行里不用声明 fs 权限就能读写。
ts
showOpenDialog(options?: OpenDialogOptions): Promise<string[] | undefined>
showSaveDialog(options?: SaveDialogOptions): Promise<string | undefined>用户取消时为 undefined。
| 选项 | 说明 |
|---|---|
title | 标题 |
defaultPath | 默认位置:已存在的目录为起始目录;其他绝对路径为「父目录 + 文件名」;只有文件名时预填文件名 |
filters | [{ name: '图片', extensions: ['png', 'jpg'] }] |
properties | 打开对话框:openFile、openDirectory、multiSelections、createDirectory(macOS);保存对话框:createDirectory(macOS) |
同时写 openFile 与 openDirectory 时只能选文件夹。为兼容 uTools,其他选项(buttonLabel、message 等)会被接受但不生效。
ts
const paths = await window.ling.showOpenDialog({
title: '选择图片',
filters: [{ name: '图片', extensions: ['png', 'jpg', 'webp'] }],
properties: ['openFile', 'multiSelections'],
})系统目录
ts
getPath(name: 'home' | 'temp' | 'desktop' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos'): Promise<string>不需要权限。系统没有该目录时以 not_found 失败。
文件图标
ts
getFileIcon(filePath: string): Promise<string>返回图标的 Data URL:
- 文件或文件夹的绝对路径 → 它自己的图标(插件目录外需要
fs.read); - 带点的扩展名(如
'.pdf')→ 该类型的图标; 'folder'→ 通用文件夹图标。
尺寸约 64 像素(Windows 上扩展名与文件夹为 32 像素)。getFileIconAsync 与它相同。
读取其他应用
读取的都是唤起搜索框之前最前面的那个应用。
| 方法 | 说明 | 权限 |
|---|---|---|
getForegroundApp(): Promise<{ name, path } | null> | 之前的前台应用:显示名和路径(可交给 getFileIcon);前台是桌面时为 null。适合显示「粘贴到 某应用」 | |
readCurrentFolderPath(): Promise<string> | 之前的前台访达 / 资源管理器窗口所在的文件夹;前台是桌面时返回桌面目录 | foreground |
readCurrentBrowserUrl(): Promise<string> | 之前的前台浏览器当前标签页的网址 | foreground |
- 前台不是文件管理器 / 浏览器、窗口已关闭、停在「此电脑」「回收站」等虚拟位置时,以
not_found失败。 - macOS 第一次读取时,系统会弹「自动化」授权框;用户拒绝时以
permission_denied失败。 - 浏览器支持:macOS 上的 Safari 与 Chrome、Edge、Brave、Arc、Vivaldi、Opera(不支持 Firefox);Windows 上的 Chrome、Edge、Firefox、Brave、Vivaldi、Opera。Windows 上返回的是地址栏里的文字,可能没有
https://。
屏幕与取色
显示器信息与坐标换算不需要权限:
| 方法 | 说明 |
|---|---|
getAllDisplays(): Promise<Display[]> | 全部显示器 |
getPrimaryDisplay(): Promise<Display> | 主显示器 |
getDisplayNearestPoint(point): Promise<Display> | 点所在(或最近)的显示器 |
getDisplayMatching(rect): Promise<Display> | 与矩形重叠最多的显示器 |
screenToDipPoint(point) / dipToScreenPoint(point) | 物理像素 ↔ 逻辑像素(DIP),点 |
screenToDipRect(rect) / dipToScreenRect(rect) | 物理像素 ↔ 逻辑像素(DIP),矩形 |
Display:{ id, label?, bounds, workArea, workAreaSize, scaleFactor },坐标与尺寸为逻辑像素,scaleFactor 为缩放比例(如 Windows 125% 缩放时为 1.25),workArea 不含任务栏、菜单栏。
需要 screen 权限:
| 方法 | 说明 |
|---|---|
getCursorScreenPoint(): Promise<Point> | 鼠标位置(逻辑像素) |
screenColorPick(callback?): Promise<{ hex, rgb } | null> | 屏幕取色:显示放大镜,用户单击取色、Esc 取消(为 null)。hex 如 #59636E,rgb 如 rgb(89, 99, 110) |
macOS 上取色和截图需要「屏幕录制」权限,第一次会弹系统授权框,授权后要重启 lingtools;没有权限时以 permission_denied 失败。
截图见 截图。
拼音匹配
ts
pinyin.match(query: string, texts: string[], options?: { notations?: PinyinNotation[]; limit?: number }): Promise<PinyinMatch[]>用 lingtools 统一的规则做中文拼音搜索,插件不用自己打包拼音库,结果和主搜索框一致。不需要权限。
ts
const titles = ['计算稿纸', '剪贴板历史', '截图']
const hits = await window.ling.pinyin.match('jt', titles)
// [
// { index: 2, start: 0, end: 2, rank: 'exact' }, 截图
// { index: 1, start: 0, end: 2, rank: 'prefix' }, 剪贴板历史
// ]- 默认按原文、全拼、首字母匹配;
notations可加fullTone(带声调全拼)和双拼方案xiaohe、ziranma、microsoft、abc、jiajia、thunisoft。 - 每项结果:
index(在texts里的下标)、start/end(命中位置,可直接用于高亮)、rank(exact整段命中 >prefix开头命中 >contains中间命中),按rank排序。