能力不是作者在页面里猜出来的,也不是 renderer 单方面发明的。客户端/设备在 session handshake 中报告 DeviceCaps;AUP 定义 capability 形状和共享 degradation chain;具体 target 根据已报告能力做呈现。
DeviceCaps 至少包含 platform、formFactor 与每个 primitive 的 primitives map。primitive 的当前能力值是:
| 值 | 含义 |
|---|---|
native | 由 native renderer 完整实现 |
webview | 由 WebView renderer 完整实现 |
partial | 可呈现,但部分 props 不受支持 |
unsupported | 无法直接呈现,尝试共享降级链 |
display、input 和 features 可以提供额外设备上下文,但它们不是给作者绕过 renderer 支持范围的权限开关。
当前有显式链的 primitive
2.0.0-beta.25 的共享降级表目前只定义以下 9 条:
| 原 type | 依次尝试 |
|---|---|
globe | map → media → text |
chart | table → text |
map | media → text |
editor | input → text |
canvas | media → text |
rtc | unsupported |
calendar | table → text |
time | text |
overlay | text |
native、webview 与 partial 都被当前算法视为“可支持”。如果链走到 unsupported 或没有任何可支持 fallback,tree 会得到明确的 text/unsupported 标记;这不是一份等价体验的保证。
尤其要注意:一个未知或 custom type 若没有显式 degradation chain,当前实现会原样通过,而不是自动转成 text。因此“我们有降级”不等于“任何 node 都能在任何设备安全显示”。
静态 document 上的 chart
chart 是跨设备 primitive,在完整交互 Web 表面可以用 Chart.js 呈现。站点文档使用的静态 document target 不同:
| 事实 | 当前边界 |
|---|---|
| Document 能力 | DEVICE_CAPS_DOCUMENT 不声明 chart,能力值为 unsupported |
| 共享降级链 | chart → table → text |
| document 上实际得到什么 | 一张表,不是 live 图;该路径不加载 Chart.js、canvas 或 CDN |
| 数据 reshape | 运行时若包含静态 reshape(arc#3447 / arc#3458),内联 labels / datasets(或单序列 data)会变成真实表格列与行,而不是空的 “No data” 表 |
| 版本门槛 | 已发布版本字符串 2.0.0-beta.28 早于该 reshape 提交。仅报告 2.0.0-beta.28、但由更晚 checkout 构建的 CLI 可能已 reshape;纯 pre-reshape 构建仍可能显示 “No data”。在发行版同时具备 document chart 能力(或专用 document chart renderer)并在本站复验之前,不要把文档里的 live chart 写成已支持 |
| Markdown 写法 | 没有已定义的 ::chart Markdown 指令;不要在站点内容中发明 |
| 文档 sample 策略 | 公开文档不得把 live chart sample 写成 document 能力。静态页需要数据时,优先用普通 Markdown 或 AUP table |
本站文档基线实测:arc --version 为 2.0.0-beta.28,对照已含 reshape 的本地 Arc checkout 时,document 仍报告 chart 为 unsupported;对内联 bar chart 调用 renderToHtml 得到的是带数据的语义 <table>(有 title 时含 caption),不是图表图形。完整证据见内部能力矩阵(docs/aup/capability-matrix.md §0.6)。
primitive 与 Web widget 的区别
当前有 18 个跨设备 primitive。另有 42 个 Web-only widget,它们可能在 Web runtime 有 renderer,但并不属于 DeviceCaps.primitives 的跨设备能力表。使用 terminal、frame、breadcrumb 或类似 widget 时,应把它当成 Web target 的能力并在浏览器验收,而不是为它假定 mobile/terminal fallback。
作者的验收顺序
- 先只用你要支持 target 明确支持的 primitive。
- 若使用上表 9 个可能退化的 type,写下仍可接受的文字/表格/媒体 fallback。
- 在真实 target 打开同一个 tree,检查呈现与 user-visible degradation 标记。
- 为 Web-only widget 写单独的 Web 验收;不要把其成功复制为跨设备结论。
查看完整名称分类时,读Primitive 类型分类与证据;交互更新的传输边界见Session、patch 与 scene。
Slides / deck 路径(web)
普通 document 页使用 DEVICE_CAPS_DOCUMENT。含 deck 的树(Markdown slides: true)可走 DEVICE_CAPS_DECK,使 chart、map、calendar、overlay、canvas、explorer、surface、chat、globe(map shell 变体)等保留 progressive-enhance / readonly shell,而不是文章降级链(arc#4005 / #4011 / #4012)。这不是「任意文档页都能 live Chart.js」的通用产品声明——普通文章仍会降级这些类型。
Markdown directive 属性仍是字符串;tour 里 JSON 数组属性还需运行时 coercion(arc#4013)。