TypeScript 类型参考

ToolZen 当前直接加载的是原生 JavaScript ESM;TypeScript 或 Vue SFC 需要在本地构建为符合规范的 .js / .mjs 文件后再上传。类型声明用于编辑器提示,不会注入运行时。

下载声明文件

下载 toolzen-plugin-api.d.ts

在插件源码项目中引用:

/// <reference path="./types/toolzen-plugin-api.d.ts" />

核心类型

type PluginEnterAction = {
  code: string
  type: 'open' | 'text' | 'regex' | 'over' | 'img' | 'file'
  payload: string
  files?: string[]
}

type PluginDetachWindowOptions = {
  title?: string
  featureCode?: string
  initialText?: string
  width?: number
  height?: number
}

type PluginInfo = {
  code: string
  name: string
  version: string
  type: 'builtin' | 'local' | 'remote'
}

type PluginTheme = 'light' | 'dark'

type PluginDialogFilter = { name: string; extensions: string[] }
type PluginOpenDialogOptions = {
  title?: string
  defaultPath?: string
  buttonLabel?: string
  filters?: PluginDialogFilter[]
  properties?: Array<'openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles'>
}
type PluginSaveDialogOptions = { title?: string; defaultPath?: string; buttonLabel?: string; filters?: PluginDialogFilter[] }
type PluginScreenPoint = { x: number; y: number }
type PluginScreenRect = { x: number; y: number; width: number; height: number }
type PluginDisplayInfo = { id: number; bounds: PluginScreenRect; workArea: PluginScreenRect; workAreaSize: { width: number; height: number }; scaleFactor: number; rotation: number; touchSupport: string }
type PluginFileScanOptions = { recursive?: boolean; includeDirectories?: boolean; includeHidden?: boolean; match?: string; limit?: number }
type PluginFileEntry = { path: string; directory: string; name: string; stem: string; extension: string; isDirectory: boolean; size: number; modifiedAt: number; createdAt: number; hidden: boolean; exists: boolean }
type PluginFileScanResult = { ok: boolean; entries: PluginFileEntry[]; errors: Array<{ path: string; code: string; message?: string }>; truncated: boolean; code?: string }
type PluginFileExistsResult = { ok: boolean; exists: boolean[]; code?: string }
type PluginFileRenameRequest = { items: Array<{ from: string; to: string }>; dryRun?: boolean; allowOverwrite?: boolean; onConflict?: 'error' | 'skip' | 'overwrite'; continueOnError?: boolean }
type PluginFileRenameResultItem = { from: string; to: string; ok: boolean; code?: string; message?: string }
type PluginFileRenameItem = { from: string; to: string; status: 'planned' | 'applied' | 'skipped' | 'failed'; reason?: string; error?: string }
type PluginFileRenameResult = { ok: boolean; dryRun: boolean; results: PluginFileRenameResultItem[]; succeeded: number; failed: number; items: PluginFileRenameItem[]; applied: Array<{ from: string; to: string }>; code?: string }
type PluginFileGrantResult = { ok: boolean; granted: string[]; rejected: Array<{ path: string; reason: string }> }
type PluginFileWriteRequest = { path: string; name?: string; data: ArrayBuffer | ArrayBufferView; mimeType?: string }
type PluginFileWriteResult = { ok: boolean; path?: string; code?: 'invalid' | 'not-granted' | 'EFBIG' | 'failed'; message?: string }
type PluginNetworkApi = { fetch: (input: string | Request, init?: RequestInit) => Promise<Response> }

type PluginDesktopSource = {
  id: string
  name: string
  kind: 'screen' | 'window'
  display_id: string
  thumbnail: string
  appIcon: string
}
type PluginDesktopSourcesOptions = {
  types?: Array<'screen' | 'window'>
  thumbnailSize?: { width: number; height: number }
  fetchWindowIcons?: boolean
}
type PluginCaptureStreamOptions = {
  sourceId?: string
  kind?: 'screen' | 'window'
  audio?: { speaker?: boolean; microphone?: boolean }
  fps?: number
  width?: number
  height?: number
}
type PluginMediaAccessType = 'screen' | 'microphone' | 'camera'
type PluginMediaAccessStatus = 'not-determined' | 'granted' | 'denied' | 'restricted' | 'unknown'
type PluginFloatWindowOptions = {
  width?: number
  height?: number
  excludeFromCapture?: boolean
  showInactive?: boolean
  persistPosition?: boolean
}

完整声明包含 ToolZenPluginApi、剪贴板、文件(含 file.write)、网络、屏幕采集(desktopCapturer / capture / systemPreferences / overlay / floatWindow)、会话持有(holdSessionReset / hideMainWindowKeepAlive)、运行环境、主题事件、JSON 存储、字符串存储、进入/退出事件和独立窗口参数。插件组件仍应把 api 视为可空值,因为浏览器预览或非宿主加载环境不会提供它。

权限与类型的对应

权限 相关类型
file:read / file:write PluginFileScanResult、PluginFileEntry、PluginFileRenameResult、PluginFileWriteRequest、PluginFileWriteResult
file:read-content PluginFileReadRequest、PluginFileReadResult
lan:discover PluginLanAdvertiseRequest、PluginLanAdvertiseResult、PluginLanDiscoverRequest、PluginLanDiscoverResult、PluginLanPeer、PluginLocalAddress
lan:scan PluginLanInterface、PluginLanScanRequest、PluginLanScanResult、PluginLanDevice、PluginLanScanCoverage
network:fetch PluginNetworkApi
screen:capture PluginDesktopSource、PluginDesktopSourcesOptions、PluginCaptureStreamOptions、PluginMediaAccessStatus、PluginScreenRect、PluginFloatWindowOptions
不需要权限 PluginScreenPoint / PluginScreenRect(显示器查询)、PluginDisplayInfo、PluginQrCodeRequest、PluginQrCodeResult、会话持有相关方法、getWindowType