API 文档

store

使用 electron-store 进行数据存储

存储位置：{userData}/Users/data/{appId}/store/{name}.json

canbox.store.get(name, key)

获取存储的值。

  • 参数
    1. string name - 存储名称，对应不同的 .json 文件
    2. string key - 存储的键
  • 应答 any - 返回存储的值

canbox.store.set(name, key, value)

设置存储的值。

  • 参数
    1. string name - 存储名称，对应不同的 .json 文件
    2. string key - 存储的键
    3. any value - 存储的值
  • 应答 void

canbox.store.delete(name, key)

删除存储的值。

  • 参数
    1. string name - 存储名称，对应不同的 .json 文件
    2. string key - 存储的键
  • 应答 void

canbox.store.clear(name)

清空指定存储的所有数据。

  • 参数
    1. string name - 存储名称，对应不同的 .json 文件
  • 应答 void

注意：每个 name 对应一个独立的 .json 文件，用于存储不同类型的数据。例如：

  • config.json - 应用配置
  • user.json - 用户数据
  • cache.json - 缓存数据

db

canbox 使用 pouchdb 作为本地存储库

pouchdb 中文教程：PouchDB 教程

Canbox 为每个 APP 生成单独的 pouchdb 存储

canbox.db.put(doc)

新增/修改数据文档

注意：创建文档时，如果没有 _id，canbox 会生成一个 _id 最后在应答内容中返回给 app

想要修改文档，参数 _rev 使必须的

  • 参数 object
  • 应答 object

canbox.db.bulkDocs(docs)

批量操作文档，支持新增、修改和删除。

  • 参数 array docs - 文档数组
  • 应答 array - 每个文档的操作结果

功能说明：

  • 新增文档：当文档没有 _id 或没有 _rev 时，canbox 会自动生成 _id 并插入新文档
  • 修改文档：当文档包含 _id 和 _rev 时，会更新现有文档
  • 删除文档：当文档包含 _deleted: true 参数时，会删除该文档（需要提供 _id 和 _rev）

注意：canbox 会自动为新文档生成 createTime，为更新文档生成 updateTime。

canbox.db.get(query)

  • 参数 object
  • 应答 object

canbox.db.allDocs(options)

获取数据库中的所有文档。

  • 参数 object options - 查询选项
  • 应答 object - 包含 total_rows、offset、rows 的结果对象

参数说明：

  • include_docs - 是否返回完整文档内容（默认 false）
  • limit - 限制返回的文档数量
  • descending - 是否倒序排列
  • startkey - 开始的文档 ID
  • endkey - 结束的文档 ID
  • skip - 跳过的文档数量

注意：allDocs 会返回数据库中的所有文档，适合用于数据遍历、统计等场景。如果只需要特定条件的文档，建议使用 find() 方法。

canbox.db.remove(doc)

  • 参数 object 需要包含 _id 和 _rev
  • 应答 object

canbox.db.find(query)

使用 Mango 查询语法查询文档。

  • 参数 object query - 查询条件对象，支持 Mango 查询语法
  • 应答 object - 包含 docs 数组的查询结果

注意：find 方法使用 PouchDB 的 Mango 查询语法，支持复杂的查询条件、排序、分页等功能。

canbox.db.createIndex(index)

创建索引以提升查询性能。

  • 参数 object index - 索引配置对象
  • 应答 object - 索引创建结果

性能提示：

  • 创建索引可以显著提升 find 查询性能
  • 建议在应用初始化时创建常用的索引
  • 索引创建是异步操作，建议在应用启动时完成

window

canbox.win.createWindow(options, params)

  • 参数
    1. options: object 参考 electron：BaseWindowsConstructorOptions
    2. params: object: {url: '', title: '', devTools: true}
      • url: 窗口加载页面相对路径，或路由路径
      • title: 窗口标题
      • devTools: 是否开启devTools，默认 false
      • ecsClose: 点击 ecs 关闭窗口，默认 false
  • 应答：窗口的id编码

canbox.win.notification(options)

  • 参数 - options: 参考electron：Notification
  • 应答

sudo

提供跨平台的提权执行命令功能，支持 Linux、macOS 和 Windows。

canbox.sudo.exec(options)

执行需要提权的命令。

  • 参数 object options - 提权选项
  • 应答 object - 包含 stdout 和 stderr 的执行结果

参数说明：

  • command - 要执行的命令（必填）
  • name - 操作名称，用于向用户提示为何需要提权（必填）

name 参数要求：

  • 只能包含字母、数字和空格（不支持中文等非 ASCII 字符）
  • 长度不超过 70 个字符
  • 建议使用英文描述，例如：'Apply Hosts Config'、'Restart Service'

平台说明：

  • Linux/macOS - 使用 sudo-prompt，会弹出系统提权对话框
  • Windows - 使用 electron-sudo，会弹出 UAC 提权对话框

注意：提权操作涉及系统安全，请谨慎使用。确保只执行必要的命令，并在 name 参数中清晰说明操作目的。

dialog

直接的封装，没有做任何修建，请求参数和应答均可参见electron的 dialog 模块

showOpenDialog

文件选择框

与 Electron showOpenDialog 一致

showSaveDialog

文件保存框

与 Electron showSaveDialog 一致

showMessageBox

消息框

与 Electron showMessageBox 一致

生命周期

registerCloseCallback

注册窗口关闭时APP的回调函数

  • 参数: Function