TableCell 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

在 Table 的数据行中展示一个单元格，支持文字、组件与自定义内容，默认以单行截断控制长内容。

使用选择

作为 TableRow 中的数据单元格。选择列与操作列角色只在启用相应能力的 DataTable 中成立；显式内容替换该单元格默认内容。

• 放在 TableRow 内，通过 columnId 对齐列；lines / tooltip 控制长内容展示。

• 选择列与操作列由 DataTable 启用；actions 单元格的显式 children 替换默认操作。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { TableCell, Badge, Link, Table, TableHeader, TableHead, TableBody, TableRow, Chip } from '@snowui-design-system/components';</script> <Table ariaLabel="Component documentation details" minWidth={620} columnWidths={{ component: 160 }}>	<TableHeader><TableRow><TableHead columnId="component">Component</TableHead><TableHead columnId="summary">Summary</TableHead><TableHead columnId="status">Status</TableHead></TableRow></TableHeader>	<TableBody><TableRow rowId="data-table">		<TableCell columnId="component" singleLine><Link onclick={(event: MouseEvent) => { event.preventDefault(); event.stopPropagation(); }} onauxclick={(event: MouseEvent) => { event.preventDefault(); event.stopPropagation(); }} href="/components/data-table">DataTable</Link><Badge count="New" variant="border" /></TableCell>		<TableCell columnId="summary" lines={2} tooltip>Coordinates search, filtering, sorting, selection, responsive row actions, and pagination while keeping table composition explicit.</TableCell>		<TableCell columnId="status" align="end"><Chip variant="background" style="color: var(--secondary-indigo);">Review</Chip></TableCell>	</TableRow></TableBody></Table>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

内置组件双模式

• parts.Tooltip：配置截断提示。

• parts.Checkbox：配置 selection 角色内置 Checkbox。

• Skeleton 是加载基础设施，不作为公开 part。

默认单元格高度为 40px，内边距上下保持 8px；左右 padding 根据最近 Table 容器宽度在 4px 到 12px 之间流动，常见窄屏宽度即收敛到每侧 4px，宽表恢复为 12px，首尾可见单元格朝向表格外缘的一侧至少 8px。Table 使用原生相邻列布局，列与列之间没有额外 gap；相邻单元格 padding 相加后的最小视觉间距为 8px。单元格内部内容默认 gap 为 8px，复合内容可直接通过 row、gap、nowrap 控制布局，不需要额外嵌套 Frame。横向内容在单元格内垂直居中，不保留行内文字基线的下行空间。row 与单行截断同时使用时仍保持横向布局；窄容器文本适配不得把该内容改为块级文字流、丢弃图文间距。

未显式固定列宽时，单元格的固有 min-content 会参与 Table 自动列宽：可换行内容保留最长不可断单词 / 片段，lines={1} 或 nowrap 保留整行。显式 columnWidths、拖动列宽或其他固定宽度优先，此时仍按 lines / tooltip 规则截断。

<TableCell columnId="name">未知长度的文字</TableCell><TableCell lines={false}><Avatar /> 任意复合内容</TableCell><TableCell row gap={1} nowrap>$19.9 <Question /></TableCell><TableCell as="selection" /><TableCell as="actions"><Button bare>更多</Button></TableCell>

as="selection" 内置行 Checkbox，需要父 TableRow 提供稳定 rowId。常驻 column 布局中 Checkbox 一直显示，左右 padding 遵循 Table 响应式计算；overlay 时才按 hover、键盘 focus 或选中状态显示。

as="actions" 不内置默认按钮，children 可放任意行动按钮。常驻 column 布局中操作一直显示；overlay 时按行 hover、键盘焦点或展开菜单显示。内部横向排列、gap 为 8px，左右 padding 遵循 Table 响应式计算。

roleLayout="overlay" 时，selection/actions 单元格自身宽度归零并 sticky 到表格左右边缘。selection 的真实 <td> 只保留 table 语义和定位锚点；Checkbox 与渐进式模糊层都放在 .snowui-table-selection-control 中，并由运行时同步为 position: fixed，固定到当前行左上角。Checkbox 默认使用 calc(var(--size-4) + 0.0625rem)（17px），在当前奇数像素行高内上下各留 16px；固定增量已登记为 Table selection 特例，不借用边框 Token，也不改变独立 Checkbox 的 16px 默认值。覆盖块不推开第一列内容，而是直接压在第一列之上。取消选择时保留覆盖块的定位；不再满足可见条件时与遮罩同步隐藏，不产生横向位移。第一数据列的透明区覆盖到 Checkbox 实际右边缘，向右使用固定 --size-5（名义 20px）过渡；根据实际控件尺寸和响应式间距定位，不按列宽缩放。渐隐遮罩与 Checkbox 可见状态同步：行 hover、键盘 focus、已选中或 force-hover 时均生效；选中后移开鼠标也保持遮罩。未选中且没有键盘可见焦点时，离开 hover 后 Checkbox 与遮罩同帧撤去，不保留淡出残影；进入渐显与键盘可聚焦性不变。

selection 覆盖块的层级必须高于第一列内容：它使用最高 z-index，并要求使用方不要再给第一列链接或图标额外提升 z-index。Checkbox 本体是真实交互控件，onCheckedChange 直接写入 Table 选择状态并停止冒泡；TableRow 同时对行左侧 32px 点击做兜底，确保浏览器即使命中到底下第一列内容，也会优先切换行选中并阻止底层链接跳转。

selection 的 .snowui-table-role-blur-layer 与 Checkbox 同容器渲染，复用 components/src/lib/progressive-blur.ts 的通用 Progressive Blur。width 控制可见渐进模糊宽度，sampleExtension 提供透明采样区，maxBlur 使用 --snowui-table-role-overlay-blur-override。selection 左侧强模糊并向右清晰；actions 方向相反。blur layer 自身 pointer-events: none 且 aria-hidden，只在行 hover、focus-within 或已选中时显示。

actions 以当前可见行的右边缘定位，横向滚动时保持在 Table 视口内。内容渐隐按实际按钮组宽度和各内容块距该边缘的距离连续计算；按钮跨越多列时，所有被覆盖的普通内容同步渐隐，不只遮住最后一列。默认透明区覆盖到最左按钮实际左边缘，向左使用固定 --size-5（名义 20px）柔和过渡；不随按钮组宽度或响应式 padding 改变，仅跟随全局 Token 缩放。selection 与 actions 遮罩相交时同时生效，不遮住控件自身。

actions 仍在右侧以 overlay 内容块显示。actions 覆盖容器默认不接收 pointer event，只有内部按钮在 hover 时恢复可见和可点，避免右侧整行 fixed 容器拦截左侧 Checkbox 或中间链接。退出 hover（且没有展开的操作菜单）时，整个 actions 浮层立即隐藏，与内容遮罩撤销同步，避免按钮及模糊层的淡出残影叠在已恢复的文字上；进入仍保留渐显，selection 的选中显示保持独立。

DataTable 增量加载的新行动效由普通 TableCell 消费：普通数据单元格同步执行 opacity 渐显，selection / actions 角色单元格保持完整 opacity。这样 hover 控件不会再与整行 opacity 相乘；使用方显式传给 TableCell 的 whileAppear / currentState 优先于内部配置。

行点击协议：点击真实链接、按钮、输入控件、label 或 ARIA button / checkbox 不切换行；点击非交互空白区域切换当前行选中态；再次点击取消选中。

Keyword

• 默认单行截断登记到当前 Table 的 TableTruncationManager；同一表只观察 viewport / table，不允许恢复逐 Cell ResizeObserver。

• 普通 Cell 未声明高级 Frame 能力时使用原生 td 快路径；高级能力存在时自动回退完整 Frame。

• 子级 Text 显式声明 lines 时成为最近的截断 owner，Cell 不再重复生成 Tooltip。

响应式操作布局

DataTable的actions单元格向默认和显式OverflowActions提供同一布局预算、缺省maxVisible=3及progressive。显式组仍可配置数量／compact／overflow和自身样式，但availableWidth不能绕过本表预算。单元格不定义按钮variant；菜单不被行预算裁切。