Props

List

名称	类型	默认值	说明
density	ListDensity	'balanced'	行的间距密度：compact（4px 上下内边距）、balanced（8px）、spacious（12px，左右内边距也放宽一档）。单行可以用自己的 density 覆盖它。
hasDividers	boolean	false	是否在相邻两行之间绘制分隔线。最后一行不会绘制，带分隔线时行不再有圆角。
edgeCompensation	'inline'	-	按每个逻辑边缘可用的容器内边距，抵消行自身的左右内边距，让行内文字与同级标题对齐。它读取容器发布的 --container-padding-inline-start 与 --container-padding-inline-end，没有发布时按 0 处理，因此不会把行拉出容器之外。省略时行的位置不变。
listStyle	ListMarkerStyle	'none'	每行前面的标记：none、disc（实心圆点）、circle（空心圆点）、decimal（序号）。decimal 会改用 <ol> 渲染。
start	number	1	有序列表的第一个编号，仅在 listStyle="decimal" 时生效。同时写入 <ol> 的 start 属性和 CSS 计数器。
header	string	-	列表上方的纯文本标题，会以 aria-labelledby 与列表关联。需要富文本时改用 header 插槽。

ListItem

名称	类型	默认值	说明
label	string | number	-	标识这一行的主要文字。字符串和数字会自动单行截断；需要富文本时改用 label 插槽。
description	string | number	-	标签下方的次要文字，同样会自动单行截断；需要多行或富文本时改用 description 插槽。
density	ItemDensity	-	覆盖所在 List 给定的密度。留空时继承列表的密度；不在列表中时按 balanced 处理。
onClick	(event: MouseEvent) => void	-	点击处理函数。给出后行内会渲染一个占满内容区的按钮，并启用悬停与按下状态。模板里写 @click 即可。
interactiveRef	MaybeRefOrGetter<HTMLElement | null | undefined>	-	指向行内已经承载键盘操作与动作的控件（例如 startContent 中的复选框）。行会变成放大的点击区域，把表层点击转发给该控件，并且不再渲染自己的按钮，因此不会多出一个 Tab 停留点。与 onClick、href 互斥，设置后二者会被忽略。
href	string	-	链接地址。给出后行内会渲染一个链接元素。
target	'_blank' | '_self'	-	链接打开方式，仅在给出 href 时生效。_blank 会自动补上 noopener 和 noreferrer。
rel	string	-	链接关系标记，会与自动补充的标记合并去重。
isDisabled	boolean	false	禁用状态。行会变成惰性（不响应指针事件），内容调暗，并写入 aria-disabled="true"。行带有自己的 role 时不设置为惰性，由父级负责。
isSelected	boolean	false	选中状态。角色允许时写入 aria-selected="true"，否则写入 aria-current="true"；使用方自己传入的 aria-current 优先。

Item

名称	类型	默认值	说明
as	string | Component	'div'	根元素。行带有 role 时才可以传入组件，这样键盘操作仍由父级负责，行不会多出一个 Tab 停留点。
align	'center' | 'start'	'center'	起始与结束内容插槽的垂直对齐方式。start 用于两端内容高于一行文字的场景。
labelLines	number	-	标签截断前的最大行数。字符串标签留空时按单行截断，插槽内容不截断。
descriptionLines	number	-	描述截断前的最大行数。字符串描述留空时按单行截断，插槽内容在 stacked 布局下不截断。
layout	'stacked' | 'inline'	'stacked'	标签与描述的排布。inline 让两者共用一行，描述优先被省略，因此行高固定，适合放进触发器这类固定高度的容器。
isHighlighted	boolean	false	高亮状态，也就是键盘焦点和悬停时使用的外观。菜单类组件用它表示当前定位到的行。

Item 同时接受 ListItem 的全部属性，以及 label、description、density、onClick、interactiveRef、href、target、rel、isDisabled、isSelected。

插槽

List

名称	说明
default	列表的条目，通常是 ListItem。
header	列表上方的标题内容，会以 aria-labelledby 与列表关联。

ListItem / Item

名称	说明
startContent	标签之前的起始内容：图标、头像或复选框。
label	富文本形式的标签，会替代 label 属性，并且不套用自动截断。
description	富文本形式的描述，会替代 description 属性。
endContent	标签之后的结束内容：徽章、时间戳或箭头。
marker	行首的标记，作为行的直接子元素渲染。仅 Item 直接提供，ListItem 会根据列表的 listStyle 自行填充。

暴露的方法

名称	签名	说明
element	ComputedRef<HTMLUListElement | HTMLOListElement | null>	列表元素本身；带有头部时组件外层还有一个包裹元素，它仍是这个列表元素。

ListItem 和 Item 另外暴露 element（根元素）、focus() 与 blur()，聚焦时会落在行内真正可聚焦的控件上。

原生属性

List

根元素是 <ul>，listStyle="decimal" 时是 <ol>；给出 header 时外层会多一个包裹元素。

以下内容传入列表元素：

• HTML 属性。
• aria-* 属性。
• data-* 属性。
• class。
• style。

组件自己写入 role="list"、data-density、data-dividers、data-list-style 与 data-edge-compensation。未渲染 header 时，使用方传入的 aria-labelledby 会保留；渲染了 header 时由组件的标题接管。

ListItem / Item

根元素默认是 <div>，ListItem 是 <li>。

以下内容传入根元素：

• HTML 属性（role、id 等）。
• aria-* 属性，使用方传入的 aria-current 优先于选中状态推导出的值。
• data-* 属性。
• class。
• style。

组件自己写入 data-density、data-align、data-interactive、data-selected、data-disabled、data-highlighted、data-inert、aria-disabled 与推导出的 aria-selected / aria-current，这些属性不会被传入的同名属性覆盖。