LaLaWatch
API_REFERENCE
编辑
2026-08-19
undefined
00

目录

Zima Client V2 API 参考文档
📡 IPC 通信 API
约定说明
🔧 全局 API
配置管理
config:get (R→M)
config:set (R→M)
config:delete (R→M)
config:changed:* (M→R)
国际化
$t (R→M)
i18n:changeLanguage (R→M)
应用控制
app:getVersion (R→M)
app:quit (R→M)
app:openExternal (R→M)
对话框
dialog:selectFolder (R→M)
dialog:selectFile (R→M)
📱 设备管理 API
设备发现
device:discover:start (R→M)
device:discover:stop (R→M)
device:discovered (M→R)
设备连接
device:connect (R→M)
device:disconnect (R→M)
device:testConnection (R→M)
device:getInfo (R→M)
🌐 ZeroTier API
服务管理
zerotier:checkInstallation (R→M)
zerotier:checkRunning (R→M)
zerotier:start (R→M)
zerotier:stop (R→M)
网络管理
zerotier:networks (R→M)
zerotier:join (R→M)
zerotier:leave (R→M)
zerotier:getNetworkMembers (R→M)
💾 文件系统 API
SMB 挂载
smb:mount (R→M)
smb:unmount (R→M)
smb:listMounts (R→M)
文件浏览
zimaos:listFiles (R→M)
zimaos:createFolder (R→M)
📦 备份 API
备份任务管理
backup:create (R→M, 双向)
backup:progress (M→R)
backup:completed (M→R)
backup:error (M→R)
backup:list (R→M)
backup:pause (R→M)
backup:resume (R→M)
backup:cancel (R→M)
backup:delete (R→M)
🪟 窗口管理 API
窗口控制
window:minimize (R→M)
window:maximize (R→M)
window:close (R→M)
window:isMaximized (R→M)
窗口创建
window:openDevice (R→M)
window:openBackup (R→M)
window:openMain (R→M)
🔔 通知 API
notification:show (R→M)
📊 日志 API
log:info (R→M)
log:warn (R→M)
log:error (R→M)
🎨 主题 API
theme:set (R→M)
theme:get (R→M)
🔄 更新 API
update:check (R→M)
update:download (R→M, 双向)
update:progress (M→R)
update:downloaded (M→R)
update:install (R→M)
📝 完整示例
设备连接完整流程
文件备份完整流程
🔍 类型定义
全局类型
📚 相关文档

Zima Client V2 API 参考文档

IPC 通道、主进程 API 和渲染进程 API 完整参考

📡 IPC 通信 API

约定说明

  • R→M: 渲染进程调用主进程（使用 ipcRenderer.invoke）
  • M→R: 主进程推送到渲染进程（使用 webContents.send）
  • 双向: 请求-响应 + 事件推送模式

🔧 全局 API

配置管理

config:get (R→M)

获取配置项

typescript
const value = await window.ipcRenderer.invoke('config:get', key: string)

参数:

  • key: 配置键名（支持点号路径，如 'connection.device'）

返回: 配置值（any）

示例:

typescript
const language = await window.ipcRenderer.invoke('config:get', 'language')
// 返回: 'zh_CN' | 'en_US' | 'system'

const device = await window.ipcRenderer.invoke('config:get', 'connection.device')
// 返回: 设备 ID 字符串或 undefined

config:set (R→M)

设置配置项

typescript
await window.ipcRenderer.invoke('config:set', key: string, value: any)

参数:

  • key: 配置键名
  • value: 配置值

返回: void

示例:

typescript
await window.ipcRenderer.invoke('config:set', 'language', 'zh_CN')
await window.ipcRenderer.invoke('config:set', 'connection.autoSambaMount', true)

config:delete (R→M)

删除配置项

typescript
await window.ipcRenderer.invoke('config:delete', key: string)

参数:

  • key: 配置键名

返回: void

config:changed:* (M→R)

配置变更通知（自动推送）

typescript
window.ipcRenderer.on('config:changed:connection.autoSambaMount', (event, newValue) => {
  console.log('自动 SMB 挂载配置变更:', newValue)
})

事件名: config:changed:${key}
数据: 新的配置值

国际化

$t (R→M)

翻译文本

typescript
const text = await window.ipcRenderer.invoke('$t', key: string)

参数:

  • key: 翻译键名（如 'show', 'quit'）

返回: 翻译后的文本（string）

示例:

typescript
const showText = await window.ipcRenderer.invoke('$t', 'show')
// 返回: '显示' (中文) 或 'Show' (英文)

i18n:changeLanguage (R→M)

切换语言

typescript
await window.ipcRenderer.invoke('i18n:changeLanguage', lang: string)

参数:

  • lang: 语言代码（'zh_CN' | 'en_US'）

返回: void

应用控制

app:getVersion (R→M)

获取应用版本

typescript
const version = await window.ipcRenderer.invoke('app:getVersion')

返回: 版本号字符串（如 '2.3.1'）

app:quit (R→M)

退出应用

typescript
await window.ipcRenderer.invoke('app:quit')

返回: void（应用将退出）

app:openExternal (R→M)

在系统默认浏览器中打开 URL

typescript
await window.ipcRenderer.invoke('app:openExternal', url: string)

参数:

  • url: 要打开的 URL

返回: void

示例:

typescript
await window.ipcRenderer.invoke('app:openExternal', 'https://www.zimaspace.com')

对话框

dialog:selectFolder (R→M)

打开文件夹选择对话框

typescript
const path = await window.ipcRenderer.invoke('dialog:selectFolder')

返回: 选中的文件夹路径（string）或 undefined（用户取消）

示例:

typescript
const folder = await window.ipcRenderer.invoke('dialog:selectFolder')
if (folder) {
  console.log('选中的文件夹:', folder)
  // 输出: /Users/xxx/Documents
}

dialog:selectFile (R→M)

打开文件选择对话框

typescript
const path = await window.ipcRenderer.invoke('dialog:selectFile', options?: {
  filters?: Array<{ name: string; extensions: string[] }>
  properties?: string[]
})

参数:

  • options: 可选配置
    • filters: 文件类型过滤器
    • properties: 对话框属性（如 ['openFile', 'multiSelections']）

返回: 选中的文件路径（string）或 undefined

📱 设备管理 API

设备发现

device:discover:start (R→M)

开始设备发现

typescript
await window.ipcRenderer.invoke('device:discover:start', options?: {
  timeout?: number      // 超时时间（毫秒），默认 5000
  method?: 'udp' | 'zerotier' | 'all'  // 发现方式，默认 'all'
})

返回: void（发现的设备通过 device:discovered 事件推送）

示例:

typescript
// 开始发现
await window.ipcRenderer.invoke('device:discover:start', {
  timeout: 10000,
  method: 'all'
})

// 监听发现的设备
window.ipcRenderer.on('device:discovered', (event, device) => {
  console.log('发现设备:', device)
})

device:discover:stop (R→M)

停止设备发现

typescript
await window.ipcRenderer.invoke('device:discover:stop')

返回: void

device:discovered (M→R)

设备发现事件（主进程推送）

typescript
window.ipcRenderer.on('device:discovered', (event, device: Device) => {
  // 处理发现的设备
})

设备对象结构:

typescript
interface Device {
  id: string              // 设备 ID
  name: string            // 设备名称
  model: string           // 设备型号
  version: string         // ZimaOS 版本
  
  connections: {
    lan?: {
      ip: string
      port: number
      available: boolean
    }
    zerotier?: {
      ip: string
      networkId: string
      available: boolean
    }
  }
  
  online: boolean
  lastSeen: number        // 最后在线时间戳
}

设备连接

device:connect (R→M)

连接到设备

typescript
const result = await window.ipcRenderer.invoke('device:connect', deviceId: string, options?: {
  method?: 'lan' | 'zerotier' | 'auto'  // 连接方式，默认 'auto'
})

参数:

  • deviceId: 设备 ID
  • options: 连接选项

返回:

typescript
{
  success: boolean
  device?: Device
  error?: string
}

示例:

typescript
const result = await window.ipcRenderer.invoke('device:connect', 'zima-abc123')
if (result.success) {
  console.log('连接成功:', result.device)
} else {
  console.error('连接失败:', result.error)
}

device:disconnect (R→M)

断开设备连接

typescript
await window.ipcRenderer.invoke('device:disconnect', deviceId?: string)

参数:

  • deviceId: 设备 ID（可选，不传则断开当前连接的设备）

返回: void

device:testConnection (R→M)

测试设备连接

typescript
const result = await window.ipcRenderer.invoke('device:testConnection', {
  ip: string
  port: number
})

返回:

typescript
{
  success: boolean
  latency?: number    // 延迟（毫秒）
  error?: string
}

device:getInfo (R→M)

获取已连接设备的详细信息

typescript
const info = await window.ipcRenderer.invoke('device:getInfo')

返回: Device 对象或 null

🌐 ZeroTier API

服务管理

zerotier:checkInstallation (R→M)

检查 ZeroTier 是否已安装

typescript
const installed = await window.ipcRenderer.invoke('zerotier:checkInstallation')

返回: boolean

zerotier:checkRunning (R→M)

检查 ZeroTier 服务是否运行

typescript
const running = await window.ipcRenderer.invoke('zerotier:checkRunning')

返回: boolean

zerotier:start (R→M)

启动 ZeroTier 服务

typescript
await window.ipcRenderer.invoke('zerotier:start')

返回: void

注意: 可能需要管理员权限

zerotier:stop (R→M)

停止 ZeroTier 服务

typescript
await window.ipcRenderer.invoke('zerotier:stop')

返回: void

网络管理

zerotier:networks (R→M)

获取网络列表

typescript
const networks = await window.ipcRenderer.invoke('zerotier:networks')

返回:

typescript
Array<{
  id: string              // 网络 ID
  name: string            // 网络名称
  status: 'OK' | 'REQUESTING_CONFIGURATION' | 'ACCESS_DENIED'
  type: 'PUBLIC' | 'PRIVATE'
  mac: string             // MAC 地址
  mtu: number             // MTU
  bridge: boolean         // 是否桥接
  broadcastEnabled: boolean
  portDeviceName: string  // 虚拟网卡名称
  assignedAddresses: string[]  // 分配的 IP 地址
}>

zerotier:join (R→M)

加入 ZeroTier 网络

typescript
await window.ipcRenderer.invoke('zerotier:join', networkId: string)

参数:

  • networkId: 16 位网络 ID（如 'a0cbf4b62axxxxxx'）

返回: void

示例:

typescript
await window.ipcRenderer.invoke('zerotier:join', 'a0cbf4b62axxxxxx')

// 等待网络状态更新
setTimeout(async () => {
  const networks = await window.ipcRenderer.invoke('zerotier:networks')
  console.log('网络列表:', networks)
}, 2000)

zerotier:leave (R→M)

离开 ZeroTier 网络

typescript
await window.ipcRenderer.invoke('zerotier:leave', networkId: string)

参数:

  • networkId: 网络 ID

返回: void

zerotier:getNetworkMembers (R→M)

获取网络成员列表

typescript
const members = await window.ipcRenderer.invoke('zerotier:getNetworkMembers', networkId: string)

返回:

typescript
Array<{
  nodeId: string          // 节点 ID
  name: string            // 节点名称
  ip: string              // IP 地址
  online: boolean         // 是否在线
}>

💾 文件系统 API

SMB 挂载

smb:mount (R→M)

挂载 SMB 共享

typescript
const result = await window.ipcRenderer.invoke('smb:mount', {
  host: string            // 主机地址
  share: string           // 共享名称（如 'Data'）
  username?: string       // 用户名（可选）
  password?: string       // 密码（可选）
  mountPoint?: string     // 挂载点（可选，自动生成）
})

返回:

typescript
{
  success: boolean
  mountPath?: string      // 挂载路径
  error?: string
}

示例:

typescript
// macOS/Linux
const result = await window.ipcRenderer.invoke('smb:mount', {
  host: '192.168.1.200',
  share: 'Data',
  username: 'zima',
  password: 'password123'
})
if (result.success) {
  console.log('挂载成功:', result.mountPath)
  // 输出: /Volumes/Data (macOS) 或 /mnt/zima/Data (Linux)
}

// Windows
// 输出: Z:\ (Windows)

smb:unmount (R→M)

卸载 SMB 共享

typescript
await window.ipcRenderer.invoke('smb:unmount', mountPath: string)

参数:

  • mountPath: 挂载路径

返回: void

smb:listMounts (R→M)

获取已挂载的 SMB 列表

typescript
const mounts = await window.ipcRenderer.invoke('smb:listMounts')

返回:

typescript
Array<{
  host: string
  share: string
  mountPath: string
  timestamp: number
}>

文件浏览

zimaos:listFiles (R→M)

列出设备上的文件/文件夹

typescript
const files = await window.ipcRenderer.invoke('zimaos:listFiles', path: string)

参数:

  • path: 设备路径（如 '/Data', '/Data/Documents'）

返回:

typescript
Array<{
  name: string            // 文件/文件夹名
  path: string            // 完整路径
  type: 'file' | 'folder'
  size: number            // 大小（字节）
  modified: number        // 修改时间（时间戳）
  mimeType?: string       // MIME 类型（文件）
}>

示例:

typescript
const files = await window.ipcRenderer.invoke('zimaos:listFiles', '/Data')
console.log('文件列表:', files)
// [
//   { name: 'Documents', path: '/Data/Documents', type: 'folder', ... },
//   { name: 'Photos', path: '/Data/Photos', type: 'folder', ... },
//   { name: 'readme.txt', path: '/Data/readme.txt', type: 'file', ... }
// ]

zimaos:createFolder (R→M)

创建文件夹

typescript
await window.ipcRenderer.invoke('zimaos:createFolder', path: string)

参数:

  • path: 文件夹路径

返回: void

📦 备份 API

备份任务管理

backup:create (R→M, 双向)

创建备份任务

typescript
const taskId = await window.ipcRenderer.invoke('backup:create', {
  source: string          // 源路径（本地）
  destination: string     // 目标路径（设备）
  config: {
    incremental?: boolean // 增量备份（默认 true）
    exclude?: string[]    // 排除规则（glob 模式）
    schedule?: string     // 定时备份（cron 表达式）
  }
})

返回: 任务 ID（string）

示例:

typescript
const taskId = await window.ipcRenderer.invoke('backup:create', {
  source: '/Users/xxx/Documents',
  destination: '/Data/Backup/Documents',
  config: {
    incremental: true,
    exclude: ['*.tmp', 'node_modules/**']
  }
})

console.log('任务 ID:', taskId)

backup:progress (M→R)

备份进度更新（主进程推送）

typescript
window.ipcRenderer.on('backup:progress', (event, data: {
  taskId: string
  percent: number         // 进度百分比 (0-100)
  speed: number           // 传输速度 (bytes/s)
  transferred: number     // 已传输字节数
  total: number           // 总字节数
  eta: number             // 预计剩余时间（秒）
  currentFile: string     // 当前文件
}) => {
  // 更新 UI
})

backup:completed (M→R)

备份完成事件

typescript
window.ipcRenderer.on('backup:completed', (event, data: {
  taskId: string
  duration: number        // 耗时（秒）
  totalFiles: number      // 总文件数
  totalSize: number       // 总大小（字节）
}) => {
  // 显示完成通知
})

backup:error (M→R)

备份错误事件

typescript
window.ipcRenderer.on('backup:error', (event, data: {
  taskId: string
  error: string
  errorCode?: string
}) => {
  // 显示错误信息
})

backup:list (R→M)

获取备份任务列表

typescript
const tasks = await window.ipcRenderer.invoke('backup:list')

返回:

typescript
Array<{
  id: string
  name: string
  source: string
  destination: string
  status: 'idle' | 'running' | 'paused' | 'completed' | 'error'
  progress: {
    percent: number
    speed: number
    eta: number
  }
  createdAt: number
  lastRunAt?: number
  nextRunAt?: number
}>

backup:pause (R→M)

暂停备份任务

typescript
await window.ipcRenderer.invoke('backup:pause', taskId: string)

返回: void

backup:resume (R→M)

恢复备份任务

typescript
await window.ipcRenderer.invoke('backup:resume', taskId: string)

返回: void

backup:cancel (R→M)

取消备份任务

typescript
await window.ipcRenderer.invoke('backup:cancel', taskId: string)

返回: void

backup:delete (R→M)

删除备份任务

typescript
await window.ipcRenderer.invoke('backup:delete', taskId: string)

返回: void

🪟 窗口管理 API

窗口控制

window:minimize (R→M)

最小化当前窗口

typescript
await window.ipcRenderer.invoke('window:minimize')

返回: void

window:maximize (R→M)

最大化/还原当前窗口

typescript
await window.ipcRenderer.invoke('window:maximize')

返回: void

window:close (R→M)

关闭当前窗口

typescript
await window.ipcRenderer.invoke('window:close')

返回: void

window:isMaximized (R→M)

检查当前窗口是否最大化

typescript
const isMaximized = await window.ipcRenderer.invoke('window:isMaximized')

返回: boolean

窗口创建

window:openDevice (R→M)

打开设备连接窗口

typescript
await window.ipcRenderer.invoke('window:openDevice')

返回: void

window:openBackup (R→M)

打开备份窗口

typescript
await window.ipcRenderer.invoke('window:openBackup')

返回: void

window:openMain (R→M)

打开主窗口

typescript
await window.ipcRenderer.invoke('window:openMain')

返回: void

🔔 通知 API

notification:show (R→M)

显示系统通知

typescript
await window.ipcRenderer.invoke('notification:show', {
  title: string
  body: string
  icon?: string         // 图标路径（可选）
  silent?: boolean      // 静音模式（可选）
})

示例:

typescript
await window.ipcRenderer.invoke('notification:show', {
  title: '备份完成',
  body: '已成功备份 150 个文件',
  silent: false
})

📊 日志 API

log:info (R→M)

记录信息日志

typescript
await window.ipcRenderer.invoke('log:info', message: string)

log:warn (R→M)

记录警告日志

typescript
await window.ipcRenderer.invoke('log:warn', message: string)

log:error (R→M)

记录错误日志

typescript
await window.ipcRenderer.invoke('log:error', message: string)

🎨 主题 API

theme:set (R→M)

设置主题

typescript
await window.ipcRenderer.invoke('theme:set', theme: 'system' | 'light' | 'dark')

参数:

  • theme: 主题模式

返回: void

theme:get (R→M)

获取当前主题

typescript
const theme = await window.ipcRenderer.invoke('theme:get')

返回: 'system' | 'light' | 'dark'

🔄 更新 API

update:check (R→M)

检查更新

typescript
const result = await window.ipcRenderer.invoke('update:check')

返回:

typescript
{
  available: boolean
  version?: string
  releaseNotes?: string
  downloadUrl?: string
}

update:download (R→M, 双向)

下载更新

typescript
await window.ipcRenderer.invoke('update:download')

返回: void（进度通过 update:progress 事件推送）

update:progress (M→R)

更新下载进度

typescript
window.ipcRenderer.on('update:progress', (event, data: {
  percent: number
  transferred: number
  total: number
}) => {
  // 更新进度条
})

update:downloaded (M→R)

更新下载完成

typescript
window.ipcRenderer.on('update:downloaded', () => {
  // 提示用户重启应用
})

update:install (R→M)

安装更新并重启

typescript
await window.ipcRenderer.invoke('update:install')

返回: void（应用将重启）

📝 完整示例

设备连接完整流程

typescript
// 1. 开始设备发现
await window.ipcRenderer.invoke('device:discover:start', {
  timeout: 10000,
  method: 'all'
})

// 2. 监听发现的设备
const devices = []
window.ipcRenderer.on('device:discovered', (event, device) => {
  devices.push(device)
  console.log('发现设备:', device.name)
})

// 3. 等待发现完成
await new Promise(resolve => setTimeout(resolve, 10000))

// 4. 停止发现
await window.ipcRenderer.invoke('device:discover:stop')

// 5. 选择设备并连接
if (devices.length > 0) {
  const result = await window.ipcRenderer.invoke('device:connect', devices[0].id)
  if (result.success) {
    console.log('连接成功')
    
    // 6. 挂载 SMB
    const mountResult = await window.ipcRenderer.invoke('smb:mount', {
      host: result.device.connections.lan.ip,
      share: 'Data',
      username: 'zima'
    })
    
    if (mountResult.success) {
      console.log('SMB 挂载成功:', mountResult.mountPath)
    }
  }
}

文件备份完整流程

typescript
// 1. 选择源文件夹
const sourceFolder = await window.ipcRenderer.invoke('dialog:selectFolder')
if (!sourceFolder) return

// 2. 选择目标文件夹（设备上）
const files = await window.ipcRenderer.invoke('zimaos:listFiles', '/Data')
const targetFolder = '/Data/Backup'

// 3. 创建备份任务
const taskId = await window.ipcRenderer.invoke('backup:create', {
  source: sourceFolder,
  destination: targetFolder,
  config: {
    incremental: true,
    exclude: ['*.tmp', '.DS_Store']
  }
})

// 4. 监听进度
window.ipcRenderer.on('backup:progress', (event, data) => {
  if (data.taskId === taskId) {
    console.log(`进度: ${data.percent}%`)
    console.log(`速度: ${(data.speed / 1024 / 1024).toFixed(2)} MB/s`)
    console.log(`预计剩余: ${Math.floor(data.eta / 60)} 分钟`)
  }
})

// 5. 监听完成
window.ipcRenderer.on('backup:completed', (event, data) => {
  if (data.taskId === taskId) {
    console.log('备份完成!')
    console.log(`耗时: ${Math.floor(data.duration / 60)} 分钟`)
    console.log(`文件数: ${data.totalFiles}`)
    
    // 显示系统通知
    window.ipcRenderer.invoke('notification:show', {
      title: '备份完成',
      body: `已成功备份 ${data.totalFiles} 个文件`
    })
  }
})

// 6. 监听错误
window.ipcRenderer.on('backup:error', (event, data) => {
  if (data.taskId === taskId) {
    console.error('备份失败:', data.error)
  }
})

🔍 类型定义

全局类型

typescript
// src/preload/index.d.ts

interface Window {
  ipcRenderer: {
    invoke(channel: string, ...args: any[]): Promise<any>
    on(channel: string, listener: (event: any, ...args: any[]) => void): void
    once(channel: string, listener: (event: any, ...args: any[]) => void): void
    removeListener(channel: string, listener: Function): void
    removeAllListeners(channel: string): void
  }
  
  electron: ElectronAPI
  platform: 'darwin' | 'win32' | 'linux'
  api: CustomAPI
}

📚 相关文档

API 文档持续更新中 📖

最后更新：2025-12-03

本文作者:oyph

本文链接:

版权声明:本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！