页面 layout 决定一个 Web route 怎样组合呈现,而不是文章、产品或文档正文应该放在哪里。先从 route 与读者任务开始;再用 component 表达重复呈现、用 source 选择内容。
选择正确的 layout 层
| 需要什么 | 放在哪里 |
|---|---|
| 一个页面的默认呈现 | pages/<name>/layout.aup |
| layout 确实因 locale 不同 | pages/<name>/layout.<locale>.aup |
| 内容对象的例外呈现 | content/<type>/<slug>/layout.aup |
| 多个内容对象共享的一种 named presentation | layouts/<name>.aup,由 front matter 中的 layout: <name> 选择 |
| 反复出现的 card/header/section 呈现 | .web/components/<name>/ |
| 面向读者对象的正文和身份 | content/<type>/<slug>/content.md |
当前读取顺序是 locale AUP、默认 AUP、locale JSON、默认 JSON、再到 convention/default layout。因此新页面通常以 AUP layout 作为 source-first 选择;JSON 仍是兼容形态,但不应默认两份都复制。
按正确方向组合
- 先声明 page 或 collection route。
- 在匹配的 page/collection scope 中声明内容 source。
- 只在 layout/component contract 需要的位置使用完整
$source.<name>值。 - 用有明确 props 的可复用 Web component,而不是在每个页面复制一棵 tree。
- 只有对象真的承担不同读者任务时,才把一次性 detail layout 放在对象旁边。
Web Device 页面 layout 使用 Web-component-and-props 模型。受支持 AUP tree 也可通过 Web renderer 静态渲染,但这不代表任意 native primitive 都是合法 layout section。可复用站点呈现应使用 component;直接 tree path 只在目标支持已核验时使用。
内容对象只能选择 item-local layout.aup,或通过 layout: <name> 选择一个 named layout,不能同时声明两者。named layout 可以为它渲染的内容挂载已核验的 widget;完整的内容加 widget 形态见Markdown Slides。
运行 layout validation,并在浏览器检查最终 route。语法有效的 layout 仍可能得到空 source、错误 locale variant 或在窄宽度难以阅读的层次。
layout 机制见 用 AUP 建立页面;component 见 使用与覆盖组件。