Skip to content

系统与 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 排序。