Table 表格

pt-table 是一层包在原生 <table> 外面的壳：数据照常写 <thead> / <tbody> / <tr> / <td>，单元格不用加任何 class。外框、表头、行悬停、表尾与说明文字都是默认样式。

基础用法

里面直接写原生 table，td / th 不用加 class。外框、表头底线、行悬停、表尾与说明文字都是默认样式。

<pt-table>
  <table>
    <caption>最近 7 天的页面访问</caption>
    <thead>
      <tr>
        <th>页面</th>
        <th>访问</th>
        <th>跳出率</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>/home</td>
        <td>1,204</td>
        <td>32%</td>
      </tr>
      <tr>
        <td>/pricing</td>
        <td>486</td>
        <td>41%</td>
      </tr>
      <tr>
        <td>/docs</td>
        <td>312</td>
        <td>18%</td>
      </tr>
    </tbody>
    <tfoot>
      <tr>
        <td>合计</td>
        <td>2,002</td>
        <td>30%</td>
      </tr>
    </tfoot>
  </table>
</pt-table>

列间竖线与选中行

bordered 在默认外框之外加单元格之间的竖线。选中行写在原生属性上：<tr data-state="selected">。

<pt-table bordered>
  <table>
    <thead>
      <tr>
        <th>实验</th>
        <th>状态</th>
        <th>转化率</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>首页主图 A/B</td>
        <td>运行中</td>
        <td>4.2%</td>
      </tr>
      <tr data-state="selected">
        <td>价格页文案</td>
        <td>已结束</td>
        <td>3.8%</td>
      </tr>
      <tr>
        <td>注册按钮颜色</td>
        <td>草稿</td>
        <td>—</td>
      </tr>
    </tbody>
  </table>
</pt-table>

为什么是光 DOM

pt-table 没有影子树（shadow: false），内部的原生标签就在页面的 DOM 里，默认样式写在全局样式表 ptengine-ui.css 里，选择器全部包了 :where() —— 特异性只剩 pt-table 这一个标签。业务直接给 td / th / tr 写 className（或 Tailwind 类）就能盖过默认样式，不用拼特异性：

html

<pt-table>
  <table>
    <thead>
      <tr>
        <th class="w-[120px] text-end">访问</th>
      </tr>
    </thead>
    …
  </table>
</pt-table>

所以必须引入全局样式表（见「安装」一节）—— 没有它，pt-table 里就是一张浏览器默认样式的表格。

吸顶表头

表头吸顶默认开启。pt-table 自己就是滚动容器（overflow: auto），宽表横滚、给了高度上限就竖滚，表头粘的也是它 —— 所以要给 pt-table 一个高度上限，吸顶才会生效：

html

<pt-table style="max-height: 320px">…</pt-table>
<!-- 在定高的 flex 列里自适应 -->
<pt-table style="flex: 1; min-height: 0">…</pt-table>

不给高度上限时它一直撑到表格的完整高度、从不竖滚，表头也就不吸顶 —— 不报错，只是没效果。

会滚动的表格里如果没有可聚焦的内容（链接、按钮、复选框），键盘用户就滚不动它。这时给宿主加 tabindex="0"，并用 role="region" + aria-label 给这块滚动区域起个名字；聚焦时的焦点环与控件一致：

html

<pt-table tabindex="0" role="region" aria-label="页面访问" style="max-height: 320px">…</pt-table>

外框和圆角也长在 pt-table 这一层，不要在外面再套一层带圆角的容器：吸顶表头的背景是不透明的，会把外层容器的两个上圆角糊成直角；只有带 overflow 的这一层才会把内容裁成圆角。

不需要吸顶时关掉：原生 HTML 写 sticky-header="false"，框架里传 stickyHeader={false} （Vue :sticky-header="false"，Angular [stickyHeader]="false"）。

行状态

悬停：表体（tbody）的行悬停时压一层 --pt-interaction-hover。
选中：在行上写 data-state="selected"，铺 --pt-bg-selected。两者都是半透明叠加，选中行再悬停会再深一档。
表尾：tfoot 铺半透明的 --pt-bg-weak、字重 500，上方一条分隔线。
说明：<caption> 显示在表格下方，13px 弱化色，与表格间隔 16px。

单元格里放 pt-checkbox（或 role="checkbox" 的元素）时，这一格的尾部内边距收为 0，勾选列不会太宽。

边框

外框（1px 边 + 8px 圆角）与行之间的横线默认就有。bordered 只多出单元格之间的竖线。不要外框时直接在 pt-table 上写 border: none（或对应的 class）即可。

API

属性

属性	Attribute	类型	默认值	说明
`bordered`	`bordered`	`boolean`	`false`	列间竖线。外框与横线默认就有，这一档只多出单元格之间的竖线
`stickyHeader`	`sticky-header`	`boolean`	`true`	表头吸顶，默认开。不反射：默认为真的布尔反射成 false 等于删掉 attribute，序列化（SSR、outerHTML）后读回来又是真。关掉时在宿主上写 `data-sticky-header="false"` 给全局样式挂钩；原生 HTML 里写的 `sticky-header="false"` 样式表也直接认，JS 到达前首帧就是对的。

Table 表格 ​

为什么是光 DOM ​

吸顶表头 ​

行状态 ​

边框 ​

API ​

属性

Table 表格

为什么是光 DOM

吸顶表头

行状态

边框

API