Table

数据表家族：1 类 Header Cell + 14 类 Body Cell（对齐 Figma 全量）· DataTable 标准表 · FullWidthTable 宽版。

Import

从 @forge-ui/react 统一导入表格相关组件。

import {
  DataTable, FullWidthTable, TableCell,
  StatusBadge, ProgressBadge,
  CellText, CellMuted, CellTextSubtitle,
  CellImageText, CellFile,
  CellNumber, CellProgressValue, CellProgressBar,
  CellStatusDot, CellCode, CellRating,
  CellActions, CellLink, CellKebabMenu,
  type ColumnDef,
} from "@forge-ui/react";

Header Cell

表头单元格。通过 TableCell variant='header' + checkbox / leadIcon / sortable / children 自由裁剪出 Figma 全部形态。下方展示最完整组合 1 个，其余形态去掉对应 prop 即可。

Usage

Product

1// 最完整组合：checkbox + icon + 文字 + 排序。
2// 通过 props 自由裁剪：去掉 checkbox / leadIcon / sortable / children 即得其他变体。
3<TableCell
4  variant="header"
5  checkbox
6  leadIcon={<CardBold size={20} />}
7  sortable
8>
9  Product
10</TableCell>

Attribute	Type	Default	Description
`variant`	`'header' \| 'body'`	`'body'`	表头还是表体单元格。
`children`	`ReactNode`	`—`	标题文字。可省略以得到 icon-only header。
`leadIcon`	`ReactNode`	`—`	标题前的 20px icon（与 checkbox 等高，建议用 Bold 实心样式）。
`sortable`	`boolean`	`false`	是否显示右侧排序 ▾ 按钮。
`onSort`	`() => void`	`—`	点击排序按钮回调。
`checkbox`	`boolean`	`false`	是否显示左侧勾选框。
`checked`	`boolean`	`false`	勾选状态。
`onCheckedChange`	`(checked) => void`	`—`	勾选回调。
`checkboxColor`	`'purple' \| 'blue' \| 'green' \| 'red' \| 'orange' \| 'black'`	`'purple'`	勾选框语义色（CheckboxColor）。

Body Cell

表体单元格的 14 个内容分类（Figma Cell 页全量），每类列出代表变体。直接塞进 ColumnDef.render。

1 · Reg Text

纯文本系。CellText（主） / CellMuted（辅） / CellTextSubtitle（可带副标题）。

Title Here

Subtext here

Title Here

Subtext here

1<CellText>Title Here</CellText>
2<CellMuted>Subtext here</CellMuted>
3<CellTextSubtitle title="Title Here" subtitle="Subtext here" />

Attribute	Type	Default	Description
`CellText.children`	`ReactNode`	`—`	主文本（fg-black / 14px / semibold）。
`CellMuted.children`	`ReactNode`	`—`	辅助文本（fg-grey-900 / 14px / medium）。
`CellTextSubtitle.title`	`string`	`—`	主文本。
`CellTextSubtitle.subtitle`	`string`	`—`	副标题（fg-grey-700 / 12px）。

2 · Square Img

方形缩略图 + 文字。常用于商品、封面列。

Handmade Pouch

+3 other products

1<CellImageText src="/img.png" title="Title Here" subtitle="Subtext here" />

Attribute	Type	Default	Description
`src`	`string`	`—`	缩略图 URL。
`title`	`string`	`—`	右侧主文本。
`subtitle`	`string`	`—`	右侧副标题。
`rounded`	`'lg' \| 'full'`	`'lg'`	圆角形态：lg = 方形圆角缩略图；full = 圆形（用于头像 / 国旗）。

3 · Circle Img

圆形缩略图 + 文字。CellImageText 的 rounded="full" 变体，常用于国旗、头像。

Australia

ilahmbudi@mail.co...

1<CellImageText
2  src="/flag-au.png"
3  title="Australia"
4  subtitle="ilahmbudi@mail.co..."
5  rounded="full"
6/>

Attribute	Type	Default	Description
`src`	`string`	`—`	缩略图 URL。
`title`	`string`	`—`	右侧主文本。
`subtitle`	`string`	`—`	右侧副标题。
`rounded`	`'lg' \| 'full'`	`'lg'`	圆角形态：lg = 方形圆角缩略图；full = 圆形（用于头像 / 国旗）。

4 · User

头像 + 姓名（可选邮箱）。直接用 Avatar 组合，不需要专用 Cell —— Avatar 的 API 见 /cases/avatar。

Ilham Budiilahmbudi@mail.co...

1<div className="flex items-center gap-2">
2  <Avatar initials="IB" color="purple" size="md" />
3  <div className="flex flex-col">
4    <span className="text-fg-black text-sm font-semibold">Ilham Budi</span>
5    <span className="text-fg-grey-700 text-xs">ilahmbudi@mail.co...</span>
6  </div>
7</div>

5 · User Group

重叠头像组。overflowCount 控制超出徽章数值。

+24

1<AvatarGroup overflowCount={24}>
2  <Avatar initials="IB" color="purple" size="sm" />
3  <Avatar initials="WW" color="blue" size="sm" />
4  <Avatar initials="EH" color="green" size="sm" />
5</AvatarGroup>

Attribute	Type	Default	Description
`children`	`ReactNode`	`—`	嵌套 Avatar 组件，自动 -space-x-2 重叠。
`overflowCount`	`number`	`—`	超出徽章数值，> 0 时尾部追加 +N 圆。

6 · Badge (Circle Icon + Text)

小圆 icon 徽章 + 文字。多用于项目、分类列 —— 底层是 CircleIcon + 普通文本，API 见 /cases/badge。

Project Nameilahmbudi@mail.co...

1<div className="flex items-center gap-2">
2  <CircleIcon color="purple" size="sm"><StarLinear size={14} /></CircleIcon>
3  <div className="flex flex-col">
4    <span className="text-fg-black text-sm font-semibold">Project Name</span>
5    <span className="text-fg-grey-700 text-xs">ilahmbudi@mail.co...</span>
6  </div>
7</div>

7 · Files

文件类型 icon + 文件名 + 大小。走 FileTypeIcon，按扩展名自动配图。

annual-report.xlsx

400 kb

deck.pptx

400 kb

cover.png

1<CellFile name="report.xls" size="400 kb" />
2<CellFile name="slides.pptx" size="400 kb" />
3<CellFile name="cover.png" />

Attribute	Type	Default	Description
`name`	`string`	`—`	文件名（含扩展名，决定 icon）。
`size`	`string`	`—`	副标题文件大小，如 '400 kb'。
`icon`	`ReactNode`	`—`	自定义 icon，替代 FileTypeIcon。

8 · Numbers

数字列，两种主视觉：trend 箭头或 badge 涨跌徽章；subdued 可弱化主数值。

$400

+10%

1// 方向箭头变体（trend 为 'up' | 'down'）
2<CellNumber value="$400" trend="up" />
3 
4// 涨跌徽章变体（badge + badgeColor）
5<CellNumber value="$400" badge="+10%" badgeColor="green" />

Attribute	Type	Default	Description
`value`	`string`	`—`	主数值。
`trend`	`'up' \| 'down'`	`—`	方向箭头（不带百分比时使用）。
`badge`	`string`	`—`	涨跌徽章文字，与 badgeColor 搭配。
`badgeColor`	`'green' \| 'red' \| 'grey'`	`'green'`	徽章颜色。
`subdued`	`boolean`	`false`	弱化主数值（fg-grey-900 medium）。

底层涨跌徽章 ProgressBadge 可独立使用（用在 StatCard / Header 标题旁）：

+12%

-5%

1<ProgressBadge label="+12%" color="green" />
2<ProgressBadge label="-5%" color="red" />
3<ProgressBadge label="0%" color="grey" />

Attribute	Type	Default	Description
`label`	`string`	`—`	百分比或增量文字。
`color`	`'green' \| 'red' \| 'grey'`	`'green'`	涨跌色。

9 · Label Badge

实心胶囊徽章，底层 StatusBadge，也可在 Status 列 pill 形式复用。完整 7 色见 API 表 color。

Text Here

1<StatusBadge label="Text Here" color="purple" />
2<StatusBadge label="Text Here" color="blue" />
3<StatusBadge label="Text Here" color="yellow" />
4<StatusBadge label="Text Here" color="red" />
5<StatusBadge label="Text Here" color="cyan" />
6<StatusBadge label="Text Here" color="green" />
7<StatusBadge label="Text Here" color="grey" />

Attribute	Type	Default	Description
`label`	`string`	`—`	徽章文字。
`color`	`'purple' \| 'blue' \| 'yellow' \| 'cyan' \| 'green' \| 'red' \| 'grey'`	`'green'`	语义色，7 色对应 Figma Label Badge 分类。

10 · Status Dot

左圆点（带浅色 ring）+ 文字。对应 Figma Status 分类，常用于在线/审核等状态。emphasis 控强弱、color 切 8 色，见 API 表。

Text

1<CellStatusDot label="Text" color="purple" />

Attribute	Type	Default	Description
`label`	`string`	`—`	状态文字。
`color`	`'purple' \| 'blue' \| 'green' \| 'red' \| 'yellow' \| 'cyan' \| 'grey' \| 'black'`	`'purple'`	圆点语义色，8 色。
`emphasis`	`'strong' \| 'subtle'`	`'strong'`	文字权重：strong = fg-black semibold，subtle = fg-grey-900 medium。

11 · Progress Bar

数值 + 轨道 + 百分比。常用于 Savings、达成率列。完整 7 色见 API 表 color。

$40045%

1<CellProgressBar value="$400" percent={0} color="gray" />
2<CellProgressBar value="$400" percent={45} color="purple" />
3<CellProgressBar value="$400" percent={100} color="blue" />
4<CellProgressBar value="$400" percent={45} color="red" />
5<CellProgressBar value="$400" percent={45} color="yellow" />
6<CellProgressBar value="$400" percent={45} color="cyan" />
7<CellProgressBar value="$400" percent={100} color="green" />

Attribute	Type	Default	Description
`value`	`string`	`—`	左侧主数值（如 $400）。
`percent`	`number`	`0`	0-100 的进度百分比，自动 clamp。
`color`	`ProgressBarColor`	`'purple'`	填充色，7 色。

12 · Code

单色编号码文本，如 #302012。

#302012

1<CellCode code="#302012" />

Attribute	Type	Default	Description
`code`	`string`	`—`	编号文本，如 #302012。fg-black / 14px / semibold。

13 · Action

3 变体：icon 组（mail/phone/chat/eye/pen/trash + kebab） / 纯 kebab / 行内 CellLink。

1// 图标组（mail/phone/chat/eye/pen/trash + kebab）
2<CellActions actions={["mail", "phone", "chat", "eye", "pen", "trash"]} />
3 
4// 只 kebab
5<CellKebabMenu />
6 
7// 行内链接动作（5 色）
8<CellLink label="Link" color="green" />
9<CellLink label="Link" color="red" />

Attribute	Type	Default	Description
`actions`	`CellActionKey[]`	`[]`	'mail' \| 'phone' \| 'chat' \| 'eye' \| 'pen' \| 'trash' 的任意组合。
`showKebab`	`boolean`	`true`	是否追加 kebab menu。
`iconColor`	`string`	`'var(--fg-grey-700)'`	所有 icon 颜色（solar-icon-set 需用 color prop）。
`onAction / onKebab`	`(key) => void`	`—`	点击回调。

14 · Rating

星 + 分值。score 接受字符串或数字。

5.0

1<CellRating score="5.0" />

Attribute	Type	Default	Description
`score`	`string \| number`	`—`	右侧分值，自由格式。
`color`	`string`	`'var(--fg-yellow)'`	星形图标颜色（CSS 颜色值）。

DataTable

标准表，支持 title / subtitle / badge / checkbox / 翻页，适合中等宽度面板。

Column Definition

用 ColumnDef<Row>[] 声明列，render 里返回任意 JSX（推荐 Cell* 预设）。

const columns: ColumnDef<OrderRow>[] = [
  { key: "invoice", header: "Invoice", sortable: true, width: "w-28",
    render: (row) => <CellText>{row.invoice}</CellText> },
  { key: "product", header: "Product", flex: true,
    render: (row) => <CellImageText src={row.image} title={row.product} /> },
  { key: "status", header: "Status", width: "w-32",
    render: (row) => <StatusBadge label={row.status} color={row.statusColor} /> },
  { key: "actions", header: "", width: "w-16",
    render: () => <CellKebabMenu /> },
];

Usage

下方示例为蓝色主题 + 选中 2 行 + 底部翻页的典型订单表。

Recent Orders

Last 30 days

156

Invoice	Product	Date	Customer	Status	Amount
#302012	Handmade Pouch +3 other products	1 min ago	JC Jane Cooperjane@example.com	Pending	$121.00 +10%
#302011	Smartwatch E2 +1 other products	1 min ago	WW Wade Warrenwade@example.com	Processing	$590.00 -5%
#302002	Smartwatch E1	5 hour ago	EH Esther Howardesther@example.com	Completed	$125.00 +12%

Showing 1-3 from 156

...

1<DataTable<OrderRow>
2  title="Recent Orders"
3  subtitle="Last 30 days"
4  color="blue"
5  columns={orderColumns}
6  rows={orderRows}
7  showPagination
8  currentPage={1}
9  totalPages={16}
10  paginationLabel="Showing 1-3 from 156"
11/>

Colors

3 种主色：purple（默认）/ blue / black，影响 checkbox 与按钮。

<DataTable color="purple" ... />
<DataTable color="blue" ... />
<DataTable color="black" ... />

API

Attribute	Type	Default	Description
`columns`	`ColumnDef<Row>[]`	`—`	列定义数组，每列带 render 函数。
`rows`	`Row[]`	`—`	数据数组。
`title`	`string`	`—`	表头标题。
`subtitle`	`string`	`—`	表头副标题。
`badge`	`ReactNode`	`—`	title 右侧的 Label / 计数徽章。
`color`	`'purple' \| 'blue' \| 'black'`	`'purple'`	强调色，影响 checkbox / action 按钮。
`showCheckbox`	`boolean`	`false`	是否显示首列勾选框。
`selectedRows`	`Set<number>`	`—`	已选中行的索引集合。
`headerActions`	`ReactNode`	`—`	表头右侧操作区，常放 Datepicker + Button。
`showPagination`	`boolean`	`false`	底部是否显示翻页。
`currentPage / totalPages`	`number`	`—`	当前页与总页数。
`paginationLabel`	`string`	`—`	左下角范围说明文字。

FullWidthTable

宽版表格，额外提供 Show N 每页行数选择器，适合全屏数据管理页。

Usage

继承 DataTable 全部能力，新增 showRowCount / rowCountOptions。

Recent Orders

Text Here

Badge

Show

Invoice	Product	Date	Customer	Status	Amount
#302012	Handmade Pouch +3 other products	1 min ago	JC Jane Cooperjane@example.com	Pending	$121.00 +10%
#302011	Smartwatch E2 +1 other products	1 min ago	WW Wade Warrenwade@example.com	Processing	$590.00 -5%
#302002	Smartwatch E1	5 hour ago	EH Esther Howardesther@example.com	Completed	$125.00 +12%

Showing 1-3 from 156

...

1<FullWidthTable<OrderRow>
2  title="Recent Orders"
3  color="black"
4  showCheckbox
5  showRowCount
6  currentRowCount={10}
7  rowCountOptions={[10, 25, 50]}
8  showPagination
9  columns={orderColumns}
10  rows={orderRows}
11/>

API

Attribute	Type	Default	Description
`columns / rows`	`ColumnDef<Row>[] / Row[]`	`—`	列定义与数据，签名同 DataTable。
`showRowCount`	`boolean`	`false`	是否显示 Show N 选择器。
`currentRowCount`	`number`	`10`	每页行数当前值。
`rowCountOptions`	`number[]`	`[10, 25, 50]`	每页行数选项。
`showCheckbox / selectedRows`	`同 DataTable`	`—`	勾选逻辑。
`showPagination / currentPage / totalPages`	`同 DataTable`	`—`	翻页控制。

看所有变体 →