`media` primitive

media 是 AUP 跨设备 primitive，不是 Web Device 的 layout 组件，也不是 Web-only widget。它属于 AUP_PRIMITIVES 中的 18 个名称之一，并出现在每个 target 的 DeviceCaps.primitives map 中（取值为 native、webview、partial 或 unsupported）。

合同

字段	值
Primitive 名称	`media`
层级	AUP 跨设备 primitive（`AUP_PRIMITIVES`）
公共状态	`released`
Document 能力	`native`
共享 degradation chain	无（document 报告 native）
作者入口	AUP tree · 通用 Markdown 指令 `::media{…}` · Markdown 图片（独立 img 路径）
Document renderer / 备注	`renderer/primitives/media.ts`
Showcase 证据	Markdown 图片路径；Showcase 富媒体页

何时使用

需要带类型（image / video / audio / avatar）与可选 caption 的语义 media 节点时。

何时不要使用

不要把不受限的第三方 embed 当成受信任 media。frame 的同源/白名单规则另见 embed。行内 Markdown ![alt](src) 是另一条结构路径（image）。

Sample 合同

字段	值
目的	document target 上带 caption 的 `media` 图片
边界	本页不承诺 video/audio 产品能力；任意 embed 的信任/白名单另表；缺 `src` → placeholder
作者入口	通用叶指令 `::media{…}`（Markdown → AUP `type: media`）
表面	Web Device document
公共状态	`released`
Fallback / 失败	缺 `src` → 空 placeholder；未知 type 回落到 image 渲染
验证	下方路由 · `arc --version` = `2.0.0-beta.28`

Document sample（image）

本 sample 使用通用 Markdown → AUP 路径（::media → type: media）。资源为本站文档已使用的静态图片 URL。它不是 video、audio、avatar 或不受限第三方嵌入的证据。

源码：

::media{id="docs-prim-media-img" type="image" src="https://media.arcblock.io/lib/2f/2f757138def2b3fc.w1600.webp" alt="Illustrative documentation asset" caption="Document-target media illustration"}

渲染：

Illustrative documentation asset — Document-target media illustration

失败与限制

情形	预期结果
缺少 `src`	空的 `aup-media` placeholder（本 sample 合同不依赖损坏的远程加载）
未知 `type`	回落到 image 渲染路径
期望 frame / iframe embed API	错误表面——使用 `::embed` / frame 规则
行内 `![alt](src)`	独立 MD 结构路径，不是本 AUP `media` 节点 sample

源码（缺 src——仅 placeholder）：

::media{id="docs-prim-media-empty" type="image" alt="Missing source becomes a placeholder"}

渲染：

最小 AUP JSON 形状（交互 / full-web 写作；同一 renderer 键）：

{
  "id": "hero-shot",
  "type": "media",
  "props": {
    "type": "image",
    "src": "/assets/example.png",
    "alt": "Example",
    "caption": "Caption"
  }
}

验证证据

项	值
基线	`2026-08-09` · `arc --version` → `2.0.0-beta.28`
能力行	`docs/aup/capability-matrix.md`（内部，不对外路由）· `media`
实现	`content-reader.ts`（通用指令 → type 名）；`renderer/primitives/media.ts`
公开路由	`/en/docs/aup/primitives/media/` · `/zh/docs/aup/primitives/media/`
本地运行	`arc service start --blocklet blocklets/arcblock --port 4900` · 打开路由；确认 figure+caption 与空 placeholder
接受标准	图片 sample 显示 figure/caption；空 `src` 为 placeholder；页面不声称 video/audio/frame

证据锚点

项	值
注册表	`packages/aup/src/aup-types.ts` · `AUP_PRIMITIVES`
Document caps	`providers/runtime/web-device/src/device-caps.ts` · `DEVICE_CAPS_DOCUMENT`
Degradation	`packages/aup/src/degradation.ts` · `DEGRADATION_CHAINS`
内部矩阵	`docs/aup/capability-matrix.md`（内部，不对外路由）
Taxonomy hub	Primitive 类型分类与证据
Sample 合同规则	Live 示例：范围与合同

合同