66 lines
4.2 KiB
Markdown
66 lines
4.2 KiB
Markdown
# Web 布局工程:先拆布局,直到 Markdown 叶子
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 状态 | Active,2026-11-08 可执行参考工程与浏览器门禁已落地 |
|
||
| 包内手册 | [英文根入口](../../ext/web/index.mq.md) · [中文根入口](../../ext/web/网页/索引.mq.md) |
|
||
| 布局工具 | [layout](../../ext/web/layout/index.mq.md) · [布局](../../ext/web/布局/索引.mq.md) |
|
||
| 实现与边界 | [Web 手册优化](ext-web-handbook.md) · [Artifact](ext-web-artifact.md) · [ADR 0007](../adr/0007-web-document-endpoint.md) |
|
||
|
||
## 先建立区域树,再写内容
|
||
|
||
首页先拆成导航、主体、页脚。页脚若有左右两栏,拆成品牌与链接;链接区若还有双栏,再拆成文档与社区。继续按内部独立布局拆分,直到叶子只剩简单 Markdown 可以直接表达的内容。
|
||
|
||
```text
|
||
index.mq.md → components/index.mq.md(纵排)
|
||
├─ nav/index.mq.md → content.md
|
||
├─ main/index.mq.md → content.md
|
||
└─ footer/index.mq.md(分栏)
|
||
├─ brand/index.mq.md → content.md
|
||
└─ links/index.mq.md(分栏)
|
||
├─ docs/index.mq.md → content.md
|
||
└─ community/index.mq.md → content.md
|
||
```
|
||
|
||
父文件只导入子块、合并兄弟节点并声明一层排列。叶子文件只说明一种内容职责;内容较长时,使用相邻的普通 content.md,避免字符串转义。拆分终点不是行数或文件数量,更不是每句话建一个文件。
|
||
|
||
## 何时继续拆、何时停止
|
||
|
||
| 观察 | 决定 |
|
||
|------|------|
|
||
| 导航、正文、页脚混在一个内容块 | 拆成父级装配和三个职责块 |
|
||
| 页脚内部仍同时负责品牌与链接排布 | 再拆左右子块 |
|
||
| 链接子块内部仍包含两个独立栏目 | 继续拆到各栏目 Markdown |
|
||
| 叶子只包含标题、段落、列表、链接、表格、图片 | 停止;已可用普通 Markdown 表达 |
|
||
| 父文件含大量正文、HTML 标签、CSS 字符串 | 职责或表达方式仍未收敛,继续拆解 |
|
||
| 结构已经简单,只为减少行数而再拆 | 不必拆;以可读职责为准 |
|
||
|
||
表单、数据源、交互各有自己的领域职责,应调用对应模块,不以“Markdown 不表达交互”为由恢复整页 HTML 壳。只有确实需要兼容宿主能力时,才在隔离边界使用已有 raw/css 接口并说明原因。
|
||
|
||
## 同一表结构贯穿所有层
|
||
|
||
公共列是 `type | slot | value | attrs | style`,中文可用 `类型 | 槽 | 值 | 属性 | 样式`。使用 @ 记录表产生节点列表。
|
||
|
||
- `component.markdown` / `组件.正文`:叶子值为普通 Markdown。
|
||
- `component.wrap` / `组件.包裹`:值中保留子节点列表,可标记 nav/footer/section 等语义区域。
|
||
- `layout.stack` / `布局.纵排`:声明上下关系。
|
||
- `layout.columns` / `布局.分栏`:声明响应式横向栏目。
|
||
- `merge`:只确定兄弟顺序,不会自动产生双栏,也不提前渲染 HTML。
|
||
|
||
原生运行时提供基本布局几何,窄屏自动折叠。style 列引用类名,不承载 CSS 源码,也不会自动定义主题。父块始终保留结构值;先渲染子块再拼 HTML 会丢失这条统一路径。
|
||
|
||
## 从文件走到真正页面
|
||
|
||
[英文参考工程](../../examples/web-layout-handbook/index.mq.md)与[中文参考工程](../../examples/web-layout-handbook-zh/index.mq.md)实现上面的整个拆分树。先运行 preview.mq.md 检查真实渲染,再进入工程目录运行 serve.mq.md。
|
||
|
||
结构化 Document 显式声明 `view: main` / `视图: main`,main 返回节点;服务启动时装配一次。普通 Markdown Document 保留既有行为,Endpoint 单独处理请求期互动。改动结构或叶子内容后重启。自动数据源绑定继续使用普通 Document,避免与启动装配混用。
|
||
|
||
验收同时检查源码和产物:叶子只含普通 Markdown,父文件只表达其一层关系;桌面页脚出现真正的两层分栏,手机两层都折叠;关于页、API 仍能工作。规则清单本身不是“已经通过”的证明。
|
||
|
||
```bash
|
||
cargo test --locked --test web_handbook
|
||
node tests/web/layout.browser.cjs /absolute/path/to/preview.html
|
||
```
|
||
|
||
详细测试方式和当前能力边界见[优化记录](ext-web-handbook.md)。
|