Top Bar 顶栏

应用头部区块：前导控件、标题、搜索与操作。变窄时自动收紧（更矮、隐藏副标题、搜索收进图标），在沉浸式页面中自动加上状态栏留白。

基础用法

STopbar({
  title: 'Projects',
  subtitle: '12 active',
  search: true,                                  // expands from an icon when condensed
  actions: [new SparkTopbarAction('new', 'plus', 'New project'),
            new SparkTopbarAction('alerts', 'bell', 'Notifications')],
  onAction: (id: string) => ...,
  onSearch: (q: string) => ...
}) {
  SBadge({ text: 'Beta', variant: 'secondary' })  // optional trailing slot
}

STopbar({ title: 'Invoice #1024', leading: 'back', onBack: () => ... })
STopbar({ title: 'Gallery', translucent: true }) // backdrop blur for content scrolling underneath

网页近似预览，真机效果以 HarmonyOS 渲染为准。

API

从组件库源码中的 @Param / @Event / @BuilderParam 声明自动提取。

STopbar

应用头部（shadcn 的「站点头部」区块）：前导控件、标题 / 副标题、可选搜索、图标操作以及尾部插槽。无断点：当自身宽度小于约 520 vp 时会自动收紧（高 48 vp，隐藏副标题，搜索收进一个图标中，展开时覆盖在标题之上）。

它位于滚动内容之外（SAppShell / SSidebarInset），因此始终停留在顶部。设置 translucent 后背景为半透明并带背景模糊，适用于下方内容会滚动穿过的场景（SAppShell 即是如此）。safeArea 为沉浸式页面加上状态栏留白（在 'inset' 侧边栏布局内会自动跳过，因为其卡片已经避开了状态栏）。

扩展点：尾随闭包（位于 actions 之后）；以 WrappedBuilder 传入的 leadingBuilder / titleBuilder 区域（titleBuilder: wrapBuilder(myGlobalBuilder)；为补充性质——设置 leading: 'none' 或把 title 留空即可替换内置内容），用 condenseBelow 与 barHeight 替代固定尺寸，onBack 用于处理任何返回逻辑（内置无路由功能）。在 SSidebarProvider 内部，leading: 'auto' 会跟随侧边栏控制器（toggleable）。

属性	类型	默认值	说明
title	ResourceStr	''
subtitle	ResourceStr | undefined	undefined
leading	TopbarLeading TopbarLeading = 'auto' | 'trigger' | 'back' | 'none'	'auto'
actions	SparkTopbarAction[]	[]
search	boolean	false	显示搜索框（收紧时为一个展开的图标）
searchPlaceholder	ResourceStr	$r('app.string.spark_search_placeholder')
translucent	boolean	false	半透明、带背景模糊的背景
bordered	boolean	true
safeArea	boolean	false	加上顶部安全区留白（沉浸式页面）
condenseBelow	number	TOPBAR_CONDENSED_BELOW	当栏自身宽度低于此值时收紧（vp）
barHeight	number	0	不含安全区留白的栏高（vp；0 表示使用 --topbar-height[-condensed]，否则为 56，收紧时为 48）
leadingBuilder	WrappedBuilder<[]> | undefined	undefined	位于内置 leading 控件之后的额外前导内容（设置 leading: 'none' 即可替换它），以全局 @Builder 的 wrapBuilder(myLeading) 传入（没有 this：请渲染一个组件或读取共享状态）。
titleBuilder	WrappedBuilder<[]> | undefined	undefined	位于 title 下方或替代它的额外标题内容（面包屑、切换器……；把 title 留空即可替换），以全局 @Builder 的 wrapBuilder(myTitle) 传入。
tokens	TopbarTokens	{}	实例级外观（ADR D13）：实例 → --topbar-* 令牌 → 配方
sidebarController	SparkSidebarState | undefined	undefined	由该控制器驱动前导触发器（例如位于 SSidebarProvider 之外的顶栏）

事件	类型	默认值	说明
onBack	() => void	() => { }
onAction	(id: string) => void	() => { }
onSearchChange	(value: string) => void	() => { }
onSearch	(value: string) => void	() => { }

插槽: 子组件（尾随闭包）