工程结构
一个用 acdev new my-app --backend 建出来的工程:
my-app/├── acde.config.jsonc 应用的配置: id、名字、图标、入口、能力├── package.json├── index.html 入口页面├── src/main.js├── src/i18n.js 选语言, 填上界面文字├── src/locales/ 每种语言一张文字表: en.js、zh.js├── server.ts 后端 (可选)├── public/ 原样复制的静态文件 (可选)└── .acde/ 构建产物, 不进 git界面语言
界面语言 一节的链接html 和 desktop 模板不把界面文字写在标记里, 而是放在 src/locales/ 下每种语言一张的表里 (en.js、zh.js, 各自 export default { key: 'text' }). src/i18n.js 只用平台自带的能力, 不依赖库:
locale按navigator.language选: 有这个标签的表就用它 (zh-TW.js), 否则用它的基础语言 (zh, 经Intl.Locale), 再否则用en. 表里没有的 key 回落到英文的文字.t(key, values)返回填好{name}占位符的文字.translate()把<html lang>设成locale, 并给每个带data-i18n="key"属性的元素填上文字; 在那之前index.html带的是lang="en".
要加一种语言, 加一个和 en.js 有同样 key 的 src/locales/<tag>.js, 再在 i18n.js 里导入它. 日期和数字用 Intl 和 locale 来格式化 (new Intl.DateTimeFormat(locale)). 框架模板保留各自脚手架写出来的界面.
配置和清单
配置和清单 一节的链接acde.config.jsonc是你写的配置, 只在构建时读."type"是"app"(一个窗口应用) 或"desktop"(一个桌面).- 清单 是构建产物
.acde/里package.json的acde字段..acde/这个目录就是一个包: 运行时跑的东西. 运行时只认清单.
acdev build 把前者变成后者. 绝大多数时候你只需要关心配置; 清单的格式见 包清单.
没有 acde.config.jsonc 的目录也能构建:
package.json的acde字段里有apps的, 当作手写的包, 原样使用 (只检查);- 否则当作默认应用: 入口
index.html, id 由package.json的name得出, 显示名取displayName或productName.
构建出来的包
构建出来的包 一节的链接应用 my-app 构建后:
.acde/├── package.json 清单├── web/ 网页, 在运行时里的地址是 /app/my-app/└── backend/ ├── server.js 打包好的后端 ├── package.json {"type": "module"} └── acde-listen.js 把后端的 listen 换成 unix socket 的 preload桌面工程是 desktop/ (地址 /desktop/<id>/)、services/<名字>.js, 以及自带应用的 apps/<id>/{web,backend}.
JS 运行时和包管理器
JS 运行时和包管理器 一节的链接工程跑在 Bun 还是 Node.js 上, 由包管理器决定: bun → Bun; npm / pnpm / yarn → Node.js. 已有的工程按 lockfile 判断, 再看 package.json 的 packageManager 字段; 两样都没有时, 工程跑在 acdev 自己跑的那个 JS 运行时上. acdev new 会写上 packageManager.
Node.js 上 acdev 用工程自己的 Vite 打包 (所以自带模板在 npm / pnpm / yarn 下会带上 vite 开发依赖); Bun 上用 Bun.build. 两边的打包规则相同.
SDK
SDK 一节的链接工程的开发依赖里有一个 @dopame/acde-api, 是这一版 acdev 自带的 SDK, 写的是它在这台机器上的路径 (file:...; SDK 不在 npm 上, 装了 acdev 的地方工程就装得上). acdev new 会装上它. 升级 acdev 之后, 工程的 SDK 比较旧时 acdev check 和 acdev dev 会说出来; acdev sdk update 把它升到这一版 acdev 配对的版本. 它提供:
- 所有
acde:模块和清单的 TypeScript 类型 (只有声明: SDK 里没有 JavaScript)
在 JS 文件里引用类型:
/// <reference types="@dopame/acde-api/app" />TypeScript 工程在 tsconfig.json 的 compilerOptions.types 里加 "@dopame/acde-api/app". 桌面的页面改用 @dopame/acde-api/shell, 它再加上只有桌面才拿得到的模块; @dopame/acde-api 声明全部.