组件解析

Web Device 没有一份脱离上下文、永恒不变的 component catalog。component 来自分层 source，精确 contract 属于目标 runtime/theme/site 中的 manifest.json 与 renderer implementation。

Sample 合同（layout 路径）

本页是 layout-component sample 路径，不是 Markdown directive 的 live 页。layout component 只有在 layout.aup（或 named layout）挂进页面壳时才会渲染。下方表格与 fence 是可复制的作者 source；真实渲染表面是已经挂载该 component 的站点页面，而不是在本文件里再做一个假 HTML mock。

解析层次

当前 runtime 会按以下层次组装 component：

后面的同名文件覆盖前面的文件。这让 site 能窄范围覆盖已提供 component，但也意味着旧 article 中提到的 component 名称不自动成为每个 theme/version 的可移植合同。

三种 component surface 要分开

不要把一个 surface 的例子抬升为另一个 surface 的 contract。Markdown card 不是 .web component API；被 AUP parser 接受的 primitive 也不会自动成为 layout section。

content-card（theme + site 覆盖）

解析： 默认 theme themes/default/components/content-card/ · 本站可通过 blocklets/arcblock/.web/components/content-card/ 覆盖。

Manifest props（作者侧）： title、description、eyebrow、items、basePath、variant、readMoreHref、emptyText、headingLevel、itemHeadingLevel。

items 项常见字段为 title / slug / excerpt / category（或 meta.*）。没有 slug 表示卡片不是目的地链接（非链接外壳，而不是死的 /#/ 锚点）。

作者 source（layout 片段）

component reading slot=featured-reading component=content-card \
  variant=fleet \
  title="精选" \
  description="手工挑选的条目" \
  basePath="/$locale/" \
  emptyText="No content has been published yet." \
  items=[{title: "示例", category: "Guide", excerpt: "简短说明", slug: "articles/example"}]

空列表且给出明确文案：

component reading slot=featured-reading component=content-card \
  title="精选" \
  emptyText="No content has been published yet." \
  items=[]

当另一个 surface 已经负责列表外壳（例如搜索结果）时，传 emptyText=""，使本 component 在空列表时什么也不渲染，避免第二条 empty 文案。

真实渲染表面（不是本 docs 正文）

本 Markdown 页不 live 渲染 content-card；在这里用假截图冒充会破坏 live-example 合同。

失败与限制

page-breadcrumb（站点 component）

解析： 仅站点 blocklets/arcblock/.web/components/page-breadcrumb/（不是 default theme 的通用 catalog 条目）。

Manifest props： items（[{ label, href }] — href 不带 locale 前缀；最后一项为当前页）、currentLabel（末尾 crumb，常用 $meta.name）、collection（目前：events，供无法解析 i18n block 的 layout 使用）。

作者 source（layout 片段）

来自本站活动详情 layout（pages/events/[slug]/layout.aup）：

component crumb slot=purpose component=page-breadcrumb \
  items=[{label: "活动", href: "/events/"}] \
  currentLabel=$meta.name

currentLabel 必须是顶层 prop，因为 $meta.* 只在 prop 自身顶层解析。若需要 live 页面标题，不要只把 $meta.name 嵌在 map 条目里。

真实渲染表面

失败与限制

使用前审阅 component

不要只因 manifest 不方便读就把 component implementation 粘进页面。输入 contract 不清晰时，先从目标 manifest 与 runtime 确认；不要发明一组 props。

验证证据

编写 site-owned component 见 使用与覆盖组件；AUP tree 与 Web layout 的边界见 AUP layout 边界。