Item 列表项

一行「媒体 + 标题 / 说明 + 操作区」的内容条，用于设置项、文件、成员这类条目列表。 多条放进 pt-item-group 组成列表，媒体用 pt-item-media。

基础用法

媒体放 pt-item-media（slot="media"），标题、说明、操作区都是具名插槽；没填的部分连同间距一起收起。

<pt-item variant="outline">
  <pt-item-media slot="media" variant="icon">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
      <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"></path>
      <circle cx="12" cy="7" r="4"></circle>
    </svg>
  </pt-item-media>
  <span slot="title">张三</span>
  <span slot="description">产品设计 · zhangsan@example.com</span>
  <pt-button slot="actions" variant="secondary" size="sm">邀请</pt-button>
</pt-item>

外观与尺寸

variant 三种：default 无边框无底色、outline 1px 描边、muted 浅灰底；size="sm" 收紧内边距与间距。

<div style="display: flex; flex-direction: column; gap: 12px">
  <pt-item>
    <span slot="title">default</span>
  </pt-item>
  <pt-item variant="outline">
    <span slot="title">outline</span>
  </pt-item>
  <pt-item variant="muted">
    <span slot="title">muted</span>
  </pt-item>
  <pt-item variant="outline" size="sm">
    <span slot="title">outline · sm</span>
  </pt-item>
</div>

链接

给了 href 整条渲染成链接，带悬停状态层与键盘焦点环。链接里的操作区只放装饰图标，不要再放按钮。

<pt-item variant="outline" href="#item-link">
  <pt-item-media slot="media" variant="icon">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
      <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"></path>
      <circle cx="12" cy="7" r="4"></circle>
    </svg>
  </pt-item-media>
  <span slot="title">个人资料</span>
  <span slot="description">头像、昵称与联系方式</span>
  <svg slot="actions" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
    <path d="m9 18 6-6-6-6"></path>
  </svg>
</pt-item>

列表

pt-item-group 是 role="list"，直接子元素的 pt-item 自动成为 listitem；条目之间可以夹 pt-separator。

<pt-item-group style="border: 1px solid var(--pt-border-default); border-radius: 8px">
  <pt-item>
    <pt-item-media slot="media" variant="image">
      <img src="data:image/svg+xml,%3Csvg xmlns=%27http://www.w3.org/2000/svg%27 viewBox=%270 0 80 80%27%3E%3Crect width=%2780%27 height=%2780%27 fill=%27%238fb3d9%27/%3E%3Ccircle cx=%2740%27 cy=%2731%27 r=%2715%27 fill=%27%23f1d3bd%27/%3E%3Cpath d=%27M12 80c2-18 14-28 28-28s26 10 28 28z%27 fill=%27%232f4b6e%27/%3E%3C/svg%3E" alt=""></img>
    </pt-item-media>
    <span slot="title">张三</span>
    <span slot="description">zhangsan@example.com</span>
    <pt-button slot="actions" variant="secondary" size="sm">移除</pt-button>
  </pt-item>
  <pt-separator></pt-separator>
  <pt-item>
    <pt-item-media slot="media" variant="image">
      <img src="data:image/svg+xml,%3Csvg xmlns=%27http://www.w3.org/2000/svg%27 viewBox=%270 0 80 80%27%3E%3Crect width=%2780%27 height=%2780%27 fill=%27%238fb3d9%27/%3E%3Ccircle cx=%2740%27 cy=%2731%27 r=%2715%27 fill=%27%23f1d3bd%27/%3E%3Cpath d=%27M12 80c2-18 14-28 28-28s26 10 28 28z%27 fill=%27%232f4b6e%27/%3E%3C/svg%3E" alt=""></img>
    </pt-item-media>
    <span slot="title">李四</span>
    <span slot="description">lisi@example.com</span>
    <pt-button slot="actions" variant="secondary" size="sm">移除</pt-button>
  </pt-item>
</pt-item-group>

插槽

源包的 Item / ItemMedia / ItemContent / ItemTitle / ItemDescription / ItemActions / ItemHeader / ItemFooter 在这里合成一个元素，各部分用具名插槽填：

插槽	位置	排版
header	占满整行，在最上面	两端对齐，子元素间距 8px
media	中间一行的开头（RTL 下在右）	通常放一个 pt-item-media
title	内容列第一行	14 / 20、500、强调色，行内间距 8px
description	标题下方，间距 4px	14 / 20、正文色，超过两行截断
默认	说明下方，间距 4px	继承条目的 14 / 20
actions	中间一行的末尾（RTL 下在左）	横向排列、垂直居中，间距 8px
footer	占满整行，在最下面	两端对齐，子元素间距 8px

没填的部分整块不渲染，连同它两侧的间距一起收起。 只有标题的条目不会多出一截空的说明行， 只有媒体 + 操作区时也不会在中间留出内容列的 gap。后加或移除插槽内容（包括框架里条件渲染的说明）会跟着变。

pt-item-media 要写 slot="media" 才会落进媒体位；不写的话它进默认插槽，出现在说明下方。

外观与尺寸

属性	取值
variant	default 无边框无底色 / outline 1px 描边 / muted 浅灰底
size	md（默认）内边距与间距 16px / sm 上下 12、左右 16，间距 10px

pt-item-media 的 variant：default 裸图标（svg 20px、弱色）/ icon 32px 圆角方框（描边 + 浅灰底，svg 16px）/ image 40px 圆角缩略图（插槽里的 <img> 铺满并按比例裁切）。

链接

给了 href 整条渲染成 <a>：悬停、按下有状态层，键盘 Tab 到时出焦点环；target="_blank" 且没给 rel 时自动补 noreferrer noopener。

链接形态下操作区只放装饰（如向右的箭头图标，记得 aria-hidden="true"）。<a> 里再放按钮或链接是嵌套的可交互元素， 读屏与键盘都无法单独到达它们。需要行内按钮时不要给 href，把导航放到按钮或标题里的链接上。

列表

pt-item-group 纵向排列条目、条目之间不留间距（由条目自己的内边距或夹进来的 pt-separator 分隔，分隔线自带零外边距）。

• 宿主默认 role="list"，直接子元素里的 pt-item 自动补上 role="listitem"，读屏会念出「列表，共 N 项」。 中间隔了一层包装元素的不补（那时它的父级不是列表）。
• 宿主或条目上已经写了 role 的不覆盖：不需要列表语义时给组写 role="none"，条目也就不再补 listitem；运行时把组的 role 在 list 与别的值之间切换，条目会跟着撤掉或补回；把 role 撤掉（框架绑定成 null）等于回到默认的 list。
• 默认的 pt-separator 是装饰性的（role="none"），不破坏列表只含列表项的结构。

定制

• --pt-item-radius：条目圆角，默认 --pt-radius-md（8px）。
• 条目的边框、圆角、底色、内边距都在 part="base" 上（链接形态下就是那个 <a>）， 改外观写 pt-item::part(base)；其余各部分也开放了 part（header / media / content / title / description / actions / footer）。
• 媒体的方框在 pt-item-media::part(base) 上。

API

属性

属性	Attribute	类型	默认值	说明
href	href	string | undefined	—	给了就渲染成 `<a>`，整条可点。空串也算给了（指向当前文档，与原生 `<a href="">` 一致）
rel	rel	string | undefined	—	仅在 href 存在时有效；target="_blank" 时若未指定会自动补 noreferrer noopener
size	size	"md" | "sm"	'md'	尺寸。`md` 内边距与间距 16px；`sm` 上下 12、左右 16，间距 10px
target	target	"_blank" | "_parent" | "_self" | "_top" | undefined	—	仅在 href 存在时有效
variant	variant	"default" | "muted" | "outline"	'default'	外观。`default` 无边框无底色；`outline` 1px 描边；`muted` 浅灰底

插槽

名称	说明
（默认）	标题与说明下方的额外内容
actions	行尾的操作区（按钮、开关），横向排列、间距 8px
description	说明文字，超过两行截断
footer	占满整行的页脚，在媒体与内容之下，两端对齐
header	占满整行的页眉，在媒体与内容之上，两端对齐
media	媒体，通常是一个 `pt-item-media`（图标、头像、缩略图），在内容列之前
title	标题（14/20、500、强调色），可以夹徽标，行内间距 8px

可定制的内部元素（::part()）

part	说明
actions	操作区容器
base	外层容器（边框、底色、内边距；链接形态下就是那个 `<a>`）
content	内容列：标题 + 说明 + 默认插槽
description	说明容器
footer	页脚容器
header	页眉容器
media	媒体容器
title	标题容器

pt-item-group

插槽

名称	说明
（默认）	若干 pt-item，之间可以夹 pt-separator

pt-item-media

属性

属性	Attribute	类型	默认值	说明
variant	variant	"default" | "icon" | "image"	'default'	外观：`default` 裸图标 / `icon` 带底框的图标 / `image` 缩略图

插槽

名称	说明
（默认）	图标（svg）、图片（img）或头像

可定制的内部元素（::part()）

part	说明
base	媒体容器（尺寸、圆角、底框）