文档 / 多文件应用包

多文件应用包

应用包保存完整的文件集合。复杂应用可以直接拆分页面、数据逻辑和样式，不需要把所有代码放在一个 render 函数中。

text

app.json
index.js
pages/
  home.js
  detail.js
lib/
  todo.js
styles/
  app.css

app.json

{
  "name": "待办",
  "entry": "index.js"
}

当前运行时使用 entry 选择入口模块。name 是基础描述，桌面显示名称以创建应用时的 name 参数为准。旧 permissions 字段没有授权语义。新格式可以通过以下声明申请已登记能力；适用平台、主题模式和后台任务仍未开放。

json

{
  "formatVersion": 1,
  "sdk": { "major": 1, "minMinor": 0 },
  "entry": "index.js",
  "capabilities": {
    "required": ["data.read"],
    "optional": ["clipboard.write"]
  }
}

必需能力未知或不可用时拒绝启动；可选能力通过 platform.can 检查。ui、app.close 是基础能力。旧包默认申请数据读写及可选剪贴板能力，但仍须经过用户首次授权。能力协议正在跨端验证，尚未冻结。

省略配置时平台自动生成基础 app.json。推荐始终明确提供有效的配置和入口，避免依赖入口回退行为。

模块引用

支持包内相对路径的静态 import … from 和 export … from。建议始终写出 .js 扩展名，不使用裸模块名、CDN、绝对路径或动态 import()。

lib/todo.js

export async function loadOpen(platform, datasetId) {
  return platform.data.query(datasetId, {
    where: { done: false },
    orderBy: { field: "created_at", dir: "desc" },
    limit: 50,
  });
}

index.js

import { loadOpen } from "./lib/todo.js";

export default async function render(root, platform) {
  const todos = await platform.data.get("todo");
  const rows = await loadOpen(platform, todos.id);
  root.replaceChildren(platform.ui.title("未完成 " + rows.length));
}

当前模块加载器只处理带 from 的相对路径语法。不要使用 import "./setup.js" 这种副作用导入。.json 可作为包文件保存，但不能直接作为 JavaScript 模块导入；配置数据可放入导出对象的 .js 模块。

CSS

包内所有 .css 文件由宿主自动注入，不需要 import "./styles/app.css"。使用设计变量和布局类，避免相互覆盖的多份样式，不依赖 CSS 文件注入顺序。

文件限制

项目	当前限制
文件数量	最多 24 个，包含自动生成的 `app.json`。
扩展名	`.js`、`.json`、`.css`。
路径	相对路径，以英文字母或数字开始，允许字母、数字、下划线、连字符、点和目录分隔符。
路径约束	不能以 `/` 开始，不能包含 `..`。模块中的 `../` 引用可用于访问包内上级目录，但文件名自身不能包含 `..`。
单文件大小	当前按 JavaScript 字符串长度限制为 120,000，并非按 UTF-8 字节数计算。

上传新包时会创建完整的不可变源码快照，并切换当前版本引用。运行中的实例继续使用已加载版本；新打开的实例使用新版本。请阅读安装与更新后再提交更新。