Item 列表项

适用于列表与设置的通用行：媒体、标题、描述与操作。宽度小于 360vp 时，操作区换行到文字下方。

基础用法

SItem({ variant: 'outline' }) {
  SItemContent() {
    SItemTitle({ text: 'Basic Item' })
    SItemDescription({ text: 'A simple item with title and description.' })
  }
  SItemActions() { SButton({ text: 'Action', variant: 'outline', sizing: 'sm' }) }
}
SItem({ variant: 'muted', sizing: 'sm' }) {
  SItemMedia({ icon: 'badge-check' })
  SItemContent() { SItemTitle({ text: 'Your profile has been verified.' }) }
  SItemActions() { SIcon({ name: 'chevron-right', sizing: 16 }) }
}

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

设置分组

SItemGroup({ bordered, separators }) 把多行组合成设置卡片：贴边的行、缩进的细分隔线、着色的图标块，以及可交互行的按压反馈。

SItemGroup({ bordered: true, separators: true }) {
  Stack() {
    SItem({ interactive: true }) {
      SItemMedia({ icon: 'bell', variant: 'icon', tint: theme.colors.chart1 })
      SItemContent() {
        SItemTitle({ text: 'Notifications' })
        SItemDescription({ text: 'Push, email and in-app alerts.' })
      }
      SItemActions() { SIcon({ name: 'chevron-right', color: theme.colors.mutedForeground }) }
    }
  }.onClick(() => this.open('notifications'))
  SItem() {
    SItemMedia({ icon: 'shield-check', variant: 'icon', tint: theme.colors.chart2 })
    SItemContent() {
      SItemTitle({ text: 'Two-factor authentication' }) { SBadge({ text: 'On', variant: 'secondary' }) }
      SItemDescription({ text: 'Require a code from your phone when signing in.' })
    }
    SItemActions() { SButton({ text: 'Manage', variant: 'outline', sizing: 'sm' }) }
  }
  ...
}

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

图片与头像媒体

SItem({ variant: 'outline' }) {
  SItemMedia({ variant: 'image', src: $r('app.media.startIcon') })
  SItemContent() {
    SItemTitle({ text: 'SparkUI Gallery' })
    SItemDescription({ text: 'Version 0.1.0 · HarmonyOS' })
  }
  SItemActions() { SButton({ variant: 'ghost', sizing: 'icon-sm', icon: 'download', label: 'Download' }) }
}
SItem({ variant: 'outline' }) {
  SItemMedia() { SAvatar({ fallback: 'ER', sizing: 40 }) }
  SItemContent() {
    SItemTitle({ text: 'Evil Rabbit' })
    SItemDescription({ text: 'Last seen 5 months ago' })
  }
  SItemActions() { SButton({ text: 'Invite', sizing: 'sm', icon: 'plus' }) }
}

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

窄宽度

低于 360vp 时，操作区移到文字下方单独一行。

// same SItem, placed in a 300vp wide column

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

API

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

SItemGroup

shadcn-vue 的 ItemGroup：SItem 的纵向列表。bordered 会将其变为设置页风格的卡片（bg-card 边框、圆角 rounded-xl，条目贴合并被裁剪）；separators 会在条目之间自动绘制细分割线（设置 insetSeparators 时缩进到文字列）。

属性	类型	默认值	说明
bordered	boolean	false
separators	boolean	false
insetSeparators	boolean	true
spacing	number	0	条目之间的纵向间距，单位 vp（shadcn 的 ItemGroup 没有间距；outline 条目通常使用 16）
modifier	AttributeModifier<ColumnAttribute>	new SparkNoopModifier<ColumnAttribute>()

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

SItem

shadcn-vue 的 Item：flex flex-wrap items-center gap-4 rounded-md border border-transparent p-4 text-sm（sm：gap-2.5 px-4 py-3）。变体：default（透明）、outline（border-border）、muted（bg-muted/50）。

interactive 会增加悬停（bg-accent/50）与按下（bg-accent）反馈，并可聚焦；请通过外层 Stack() { SItem(...) { ... } }.onClick(...) 绑定操作（插槽组件无法链式绑定事件）。

响应式：当条目自身宽度小于 360vp 时，SItemActions 会换行到文字下方单独一行。

属性	类型	默认值	说明
variant	ItemVariant ItemVariant = 'default' | 'outline' | 'muted'	'default'
sizing	ItemSize ItemSize = 'default' | 'sm'	'default'
interactive	boolean	false	悬停 / 按下反馈，并可聚焦（行可点击时使用）
modifier	AttributeModifier<FlexAttribute>	new SparkNoopModifier<FlexAttribute>()

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

SItemSeparator

未使用 SItemGroup({ separators: true }) 时，条目之间的分割线。

无属性。

SItemMedia

ItemMedia：default（裸图标 / 头像，20vp 图标）、icon（size-8 rounded-sm border bg-muted，16vp 图标）或 image（size-10 rounded-sm overflow-hidden，object-cover 的 src）。条目有描述时与顶部对齐。

tint（如 theme.colors.chart2 这样的 #AARRGGBB 令牌）会为 icon 变体提供柔和的彩色底块，适合设置列表。

属性	类型	默认值	说明
icon	string | undefined	undefined
variant	ItemMediaVariant ItemMediaVariant = 'default' | 'icon' | 'image'	'default'
src	ResourceStr | undefined	undefined	image 变体所用的图片
tint	string | undefined	undefined

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

SItemContent

flex flex-1 flex-col gap-1：标题 + 描述。

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

SItemTitle

flex w-fit items-center gap-2 text-sm leading-snug font-medium；插槽中放置尾部徽标。

属性	类型	默认值	说明
text	ResourceStr	''

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

SItemDescription

text-muted-foreground line-clamp-2 text-sm leading-normal。

属性	类型	默认值	说明
text	ResourceStr	''
maxLineCount	number	2	行数截断（shadcn：2 行）

SItemActions

flex items-center gap-2，位于尾部；条目较窄时换行到文字下方（与文字对齐）。

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