APP 开发文档

文件说明

  • app.json: APP描述文件，包含 APP 启动的窗口参数
  • uat.dev.json: 开发环境配置，开发时的启动URL、打开开发工具
  • README.md: APP 说明，这个文件内容会作为 APP 信息在 canbox 展示
  • HISTORY.md: APP 版本历史，这个文件内容会作为 APP 信息在 canbox 展示
  • cb.build.json: APP 打包配置，指名打包包含的目录、文件，已经打包结果输出目录

CanBox API提示

  1. 安装 typescript ： npm i -D typescript
  2. 在项目根目录下创建目录 types，将 canbox.d.ts 放到 types 目录中
  3. 在项目根目录下创建 tsconfig.json 或 jsconfig.json 文件

tsconfig.json

{
    "compilerOptions": {
        "target": "es6",
        "module": "commonjs",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "typeRoots": ["./types", "./node_modules/@types"]
    },
    "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
    "exclude": ["node_modules"]
}

使用 JavaScript 的项目配置

{
    "compilerOptions": {
        "allowJs": true,
        "checkJs": false,
        "noEmit": true,
        "strict": false,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "maxNodeModuleJsDepth": 0,
        "target": "es6",
        "module": "commonjs",
        "forceConsistentCasingInFileNames": true,
        "typeRoots": ["./types", "./node_modules/@types"]
    },
    "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
    "exclude": ["node_modules"]
}

jsconfig.json

{
    "compilerOptions": {
        "checkJs": false,
        "strict": false,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "maxNodeModuleJsDepth": 0,
        "target": "es6",
        "module": "commonjs",
        "forceConsistentCasingInFileNames": true,
        "typeRoots": ["./types", "./node_modules/@types"]
    },
    "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
    "exclude": ["node_modules"]
}

app.json

{
    "name": "剪贴板",
    "id": "com.github.dev001.clipboard",
    "description": "一个好用的剪贴板",
    "author": "dev001",
    "repo": "https://github.com/dev001/clipboard",
    "homepage": "https://dev001.github.io",
    "main": "index.html",
    "logo": "logo.png",
    "version": "0.0.6",
    "window": {
        "minWidth": 800,
        "minHeight": 400,
        "width": 900,
        "height": 500,
        "icon": "logo.png",
        "resizable": false,
        "webPreferences": {
            "preload": "preload.js"
        }
    },
    "platform": ["windows", "darwin", "linux"],
    "categories": ["development", "utility"],
    "tags": ["json", "jsonformatter"]
}

字段说明

字段 父节点 类型 约束 说明
id string 1 app应用标识
1. 多段组成，如：com.gitee.dev001.clipboard
2. 每段都由小写字母和数字组成，且小写字母开头
3. 仅最后一段可以使用 - 符号
type string * APP 类型，设为 "webapp" 表示网页应用，不填则为普通本地应用
alias string * 英文别名，用于快捷方式命名。中文名应用建议设置此字段，方便在快速启动工具中搜索
window object 1 同 Electron 中 BrowserWindow 参数
platform array * windows, darwin, linux
插件应用支持的平台，此为 `可选项`，**当前是默认为全平台支持**
categories array * app分类，最多只取前两个
tags array * app标签，用于分类展示

categories

key 说明
education教育app
office办公
audio音频app
video视频app
game游戏app
utility工具
development开发者工具app
graphics图形应用app
network网络应用程序

WebApp 网页应用

Canbox 支持将任意网页封装为独立的桌面应用（WebApp）。与普通 APP 不同，WebApp 的 main 字段直接填入 HTTP URL，无需本地 HTML 文件。

app.json 示例

{
    "id": "com.canbox.webapp.a1b2c3d4",
    "name": "文心一言",
    "alias": "yiyan",
    "version": "1.0.0",
    "description": "Web App: https://yiyan.baidu.com",
    "author": "",
    "logo": "logo.png",
    "main": "https://yiyan.baidu.com",
    "type": "webapp",
    "webappOptions": {
        "showNavbar": false
    },
    "window": {
        "width": 1280,
        "height": 800,
        "minWidth": 800,
        "minHeight": 600
    }
}

WebApp 特殊字段

字段 类型 说明
type string 必须设为 "webapp"
main string HTTP/HTTPS URL，即网页地址
alias string 英文别名，中文名应用建议设置
webappOptions object WebApp 专属选项
webappOptions.showNavbar boolean 是否显示导航栏（后退/前进/刷新按钮），默认 false

WebApp 与普通 APP 的区别

  • main 字段填入 HTTP URL，无需本地 HTML 文件
  • asar 包内仅需 app.json + logo.png
  • 支持导航快捷键：Alt + ← / →（后退/前进）、Ctrl + R / F5（刷新）
  • 支持右键菜单：后退/前进/刷新/在浏览器中打开
  • 可配置导航栏显示（webappOptions.showNavbar）
  • 同源 target="_blank" 链接在窗口内打开，而非外部浏览器

uat.dev.json

开发配置

{
    "main": "http://localhost:5173/",
    "devTools": "detach"
}

字段说明

字段 父节点 类型 约束 说明
main development string ? 开发环境下 `development.main` 配置会覆盖 `main`
devTools development string ? 打开开发者工具，left, right, bottom, undocked, detach

preload.js

canbox开启了上下文隔离，想要使用canbox提供的api，需要在 app.json 中配置预加载脚本：

"window": {
    "webPreferences": {
        "preload": "preload.js"
    }
}

在预加载脚本中使用canbox的api：

# preload.js
canbox.hello();  # hello, hope you have a nice day

preload遵循 `CommonJS` 规范，可以使用 `require` 来引入 nodejs 模块：

cb.build.json

canbox使用asar进行打包，打包依据 cb.build.json 内容进行：

{
    "files": [
        "build/**/*",
        "preload.js",
        "logo.png",
        "app.json",
        "README.md"
    ],
    "outputDir": "./dist"
}

字段说明

字段 类型 说明
files array 相对 cb.build.json 的所有文件列表
outputDir string 相对 cb.build.json 的一个目录，打包过程中这个目录会有清空操作，所以不要放置其他需要的文件

README.md

和 app.json 同级的 README.md 文件将会被解析为 app 信息在 canbox 展示

注意：图片地址使用网络url才能正确展示

HISTORY.md

非必须文件，可以在这里记录下你的APP的版本历史。

推荐倒叙记录。