---
title: "Table 组件 — zenit Zig UI"
description: "固定列定义与自定义 cell renderer 的基础表格。列宽、header、striped row、排序入口和 cell 生命周期清晰分离。"
url: https://zenit.z.express/zh/components/table
language: zh-CN
alternate_en: https://zenit.z.express/components/table.md
alternate_es: https://zenit.z.express/es/components/table.md
alternate_ja: https://zenit.z.express/ja/components/table.md
alternate_ko: https://zenit.z.express/ko/components/table.md
alternate_fr: https://zenit.z.express/fr/components/table.md
alternate_de: https://zenit.z.express/de/components/table.md
project: zenit v0.1.0-alpha (Zig 0.15.2, macOS)
source: https://github.com/version-next/zenit
---

# Table

`ui.widgets.Table`

固定列定义与自定义 cell renderer 的基础表格。

[Video](https://zenit.z.express/media/stories/table.mp4?v=33a30d568f)

**BEHAVIOR CONTRACT**

列宽、header、striped row、排序入口和 cell 生命周期清晰分离。

**RECORDED INTERACTION**

录像展示真实 8 行数据和 sortable 列。

`examples/storybook/stories.zig:2446`

```zig
pub fn buildTable(scope: *ui.Scope, cx: *ui.Cx) anyerror!*ui.Node {
    const cols = [_]W.ColumnDef{
        .{ .id = "name", .header = "Name", .width = 160 },
        .{ .id = "role", .header = "Role", .width = 120 },
        .{ .id = "age", .header = "Age", .width = 80, .sortable = true },
    };
    const t = try W.Table(.{ .columns = &cols, .row_count = 8, .striped = true, .render_cell = tableCell }).mount(scope, cx);
    return t.wrapper;
}
```

[在 GitHub 查看源码examples/storybook/stories.zig:2446](https://github.com/version-next/zenit/blob/HEAD/examples/storybook/stories.zig#L2446)

这是 Storybook 中该 story 的原样代码（zenit 5f9add5+wip 2026-09-30）。其中 `W` 即 `ui.widgets`，`col` / `row` / `label` 是 Storybook 内的布局小工具。

### TableProps

`ui.widgets.Table`

[src/ui/components/table/mod.zig:93](https://github.com/version-next/zenit/blob/HEAD/src/ui/components/table/mod.zig#L93)

```zig
fn Table(props: TableProps) TableBuilder
```

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `columns` | `[]const ColumnDef` | `&.{}` | — |
| `row_count` | `usize` | `0` | — |
| `row_height` | `f32` | `36` | — |
| `header_height` | `f32` | `40` | — |
| `striped` | `bool` | `false` | — |
| `hoverable` | `bool` | `true` | — |
| `table_width` | `?f32` | `null` | — |
| `table_height` | `f32` | `400` | — |
| `render_cell` | `?CellRenderFn` | `null` | — |
| `on_sort` | `?core.HandlerRef` | `null` | — |
| `on_row_click` | `?core.HandlerRef` | `null` | — |

### TableResult

`ui.widgets.Table`

[src/ui/components/table/mod.zig:142](https://github.com/version-next/zenit/blob/HEAD/src/ui/components/table/mod.zig#L142)

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `wrapper` | `*Node` | — | — |
| `state` | `*TableState` | — | — |
| `vl_state` | `?*VirtualListState` | `null` | 虚拟滚动模式下的 VirtualListState（可用于动态更新 row\_count） |