跳转到内容
选择主题
选择语言简体中文

工程结构

一个用 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}.

工程跑在 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. 两边的打包规则相同.

工程的开发依赖里有一个 @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 声明全部.