在 Web Device 中,AUP 有两条相关但不同的路径。static renderer 可以把受支持的 native AUP tree 直接渲染为 HTML;而页面 layout.aup 使用的是 Web layout 与 component contract,可复用的呈现应放在站点或主题组件中,由组件承担更丰富的浏览器 HTML、CSS 与交互实现。两条路径的支持范围都由当前 Web renderer 决定,不能把“某个 AUP primitive 存在”误读成它一定是合法 layout section,或一定能在网页中呈现。
一个页面怎样取得 layout
对于 pages/<name>/,当前 runtime 以这个顺序寻找 layout:
- locale 对应的
layout.<locale>.aup,然后layout.aup; - locale 对应的
layout.<locale>.json,然后layout.json; - 由该页面目录与站点组件名称推导的兼容 convention layout;
- 默认页面 layout。
前两种是作者明确提供的 layout。新的页面应优先使用 layout.aup;layout.json 是兼容输入,不应成为新教程的默认写法。缺失 layout 并不证明页面已按你的意图呈现,它只会让 runtime 尝试后续回退。因此本地验收必须看真实页面,而不是只看目录存在。
Web layout 的组件与 native node 边界
Web renderer 会按照 Web component-and-props contract 验证页面 layout。它另有一条 static-tree renderer 路径可渲染受支持的 native AUP tree,但这不意味着任意 native primitive 都能直接作为 .web layout section。页面可引用 .web/components/ 或选中主题提供的组件;组件是承载可复用网页 HTML、样式、slots 与页面数据的稳定站点层。
概念上,页面应长成这样:
pages/index/layout.aup
│
▼
.web/components/site-home/
│
▼
HTML、CSS、主题 tokens 与内容 bindings这不是要把所有 UI 放进一个组件。它是在语义 layout 和网页实现之间保留稳定边界:页面编排结构,站点组件提供可复用的 Web 呈现。
先从页面目录开始
- 创建
pages/index/或另一个明确的pages/<name>/目录。 - 在其中写
layout.aup,引用当前站点/选定主题真实存在的 Web 组件。只有在针对目标单独验证过 static-tree renderer 及 node 支持时,才使用那条直接静态 tree 路径。 - 如果页面需要内容数据,在页面的 source/binding 层声明它;不要把文章正文抄进 layout。参见把内容绑定到页面。
- 用
arc dsl validate .检查 DSL,用arc blocklet build .和浏览器检查最终呈现。
页面可以有 locale 版本,但语言文件不是另一个页面模型。先保持同一页面与组件结构,再提供 layout.<locale>.aup 或内容的 locale 版本;只有确实需要不同结构时再分叉 layout。
常见误解
| 误解 | 当前边界 |
|---|---|
“任意 native AUP node 都能作为 layout.aup 的 section。” | 不能。static-tree rendering 是另一条路径;Web layout 使用真实的 Web component 及其 props。 |
“layout.json 是新项目推荐格式。” | 它是兼容输入;新页面优先用 DSL 来源。 |
| “目录里没有 layout,页面一定会失败。” | runtime 有 convention/default 回退;但这不是产品意图的验证。 |
| “内容对象应直接承载每个页面的 UI。” | 对象可有自己的内容或 inline layout 边界;站点页面仍应把通用呈现放在页面和组件层。 |
接下来可阅读组合页面与布局;AUP 语言本身的通用合同有意不放在这个 Web Device board 中。