List Detail 列表详情

无需路由的主从布局。容器放得下两个窗格时并排显示；放不下时一次只显示一个——选中条目会把详情推到列表之上，返回按钮再退回。

基础用法

SListDetail({ showDetail: this.open!!, listWidth: 300 }) {
  SListPane() {
    List() {
      ForEach(MAILS, (m: Mail) => {
        ListItem() { MailRow({ mail: m }) }
          .onClick(() => { this.selected = m.id; this.open = true; })
      })
    }
  }
  SListDetailPane({ title: this.mail.subject }) {     // back button when narrow
    MailView({ mail: this.mail })
  }
}

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

API

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

SListDetail

标准的主从布局（Material 的「list-detail」，iPad 分屏视图）——不涉及路由。容器能同时容纳 listWidth + minDetailWidth 时并排显示；否则只显示一个窗格，详情会推到列表之上（滑动动效，动效 key 为 'list-detail'），SListDetailPane 显示返回按钮。两个窗格始终保持挂载，因此列表会保留滚动位置。

窄屏且显示详情时：请将页面的 onBackPress 连接到 showDetail = false（或 controller.back()），以响应系统返回手势。

扩展点：controller（自行持有状态）、layoutPolicy（替换并排与否的判断）、onWideChange、motionKey；SListDetailPane 的 onBack（拦截返回）、标题栏 actions + onAction，以及 headerBuilder 区域（wrapBuilder(globalBuilder)）、empty + emptyIcon / emptyTitle / emptyDescription（或在尾随闭包内分支实现自定义空状态）。

属性	类型	默认值	说明
controller	SparkListDetailState | undefined	undefined	你自己的状态对象（无头控制）；省略时会自动创建
showDetail!!	boolean | undefined	undefined
defaultShowDetail	boolean	false
listWidth	number	0	并排显示时列表窗格的宽度（vp）；0 表示使用 --list-detail-list-width 令牌，否则为 320
tokens	ListDetailTokens	{}	实例级外观（ADR D13）：实例 → --list-detail-* 令牌 → 配方
minDetailWidth	number	360	详情需要至少达到此宽度才能与列表并排（vp）
motionKey	string	'list-detail'

事件	类型	默认值	说明
onShowDetailChange	(show: boolean) => void	() => { }
layoutPolicy	SparkSplitPolicy	sparkListDetailDefaultPolicy	根据测得的宽度决定并排（true）还是单窗格（false）（可替换）
onWideChange	(wide: boolean) => void	() => { }	在并排与单窗格之间切换时的布局

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

SListPane

列表（主）窗格。

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

SListDetailPane

详情窗格。并排时占据剩余宽度（可选带标题栏）；窄屏时它会滑动覆盖在列表之上，其标题栏会出现返回按钮，点击后退回列表。

属性	类型	默认值	说明
title	ResourceStr | undefined	undefined
showBack	boolean	true	窄屏时显示返回 / 标题栏（默认）
backLabel	ResourceStr	$r('app.string.spark_back')
empty	boolean	false	未选中任何项：显示空状态（emptyIcon / emptyTitle / emptyDescription，一个 SEmpty）而不是内容。如需自定义空状态，请保持为 false 并在尾随闭包内分支。
emptyIcon	string	'inbox'	空状态的 lucide 图标
emptyTitle	ResourceStr	$r('app.string.spark_nothing_selected')
emptyDescription	ResourceStr | undefined	undefined
actions	SparkTopbarAction[]	[]	标题栏尾端的图标按钮（onAction(id)）
headerBuilder	WrappedBuilder<[]> | undefined	undefined	位于 actions 之后的自定义标题栏尾部内容，以全局 @Builder 的 wrapBuilder(myHeader) 传入（没有 this：请渲染一个组件或读取共享状态）。

事件	类型	默认值	说明
onBack	() => boolean	() => false	点击返回按钮；处理完成时返回 true（例如弹出你自己的堆栈），即可跳过默认的弹出行为
onAction	(id: string) => void	() => { }

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