---
title: "Composant Grid — zenit Zig UI"
description: "Lignes et colonnes en deux dimensions avec cellules personnalisées. Largeurs de colonnes, hauteurs de lignes, fenêtre de défilement et coordonnées des…"
url: https://zenit.z.express/fr/components/grid
language: fr
alternate_en: https://zenit.z.express/components/grid.md
alternate_zh: https://zenit.z.express/zh/components/grid.md
alternate_es: https://zenit.z.express/es/components/grid.md
alternate_ja: https://zenit.z.express/ja/components/grid.md
alternate_ko: https://zenit.z.express/ko/components/grid.md
alternate_de: https://zenit.z.express/de/components/grid.md
project: zenit v0.1.0-alpha (Zig 0.15.2, macOS)
source: https://github.com/version-next/zenit
---

# Grid

`ui.widgets.mountGrid`

Lignes et colonnes en deux dimensions avec cellules personnalisées.

[Video](https://zenit.z.express/media/stories/grid.mp4?v=ffa00622c1)

**BEHAVIOR CONTRACT**

Largeurs de colonnes, hauteurs de lignes, fenêtre de défilement et coordonnées des cellules restent hors des nœuds de l'app.

**RECORDED INTERACTION**

Le harness fait défiler la grille et la fenêtre visible se met à jour.

`examples/storybook/stories.zig:3005`

```zig
pub fn buildGrid(scope: *ui.Scope, cx: *ui.Cx) anyerror!*ui.Node {
    const widths = [_]f32{ 90, 90, 90, 90 };
    const g = try W.mountGrid(.{
        .col_count = 4,
        .row_count = 12,
        .col_widths = &widths,
        .cell_height = 30,
        .width = 380,
        .height = 320,
        .cell_render_fn = gridCell,
    }, scope, cx);
    return g.root;
}
```

[Voir le code sur GitHubexamples/storybook/stories.zig:3005](https://github.com/version-next/zenit/blob/HEAD/examples/storybook/stories.zig#L3005)

Le code source tel quel de la story dans le Storybook (zenit 5f9add5+wip 2026-09-30). `W` désigne `ui.widgets` ; `col` / `row` / `label` sont de petits helpers de mise en page du Storybook.

### GridProps

`ui.widgets.mountGrid`

[src/ui/components/grid/state.zig:33](https://github.com/version-next/zenit/blob/HEAD/src/ui/components/grid/state.zig#L33)

```zig
fn mountGrid(props: GridProps, scope: *Scope, cx: *Cx) !GridResult
```

| Champ | Type | Défaut | Description |
| --- | --- | --- | --- |
| `row_count` | `usize` | `0` | 总行数 |
| `col_count` | `usize` | `0` | 总列数 |
| `col_widths` | `[]const f32` | `&[_]f32{}` | 每列宽度（px）。长度必须 == col\_count。 |
| `cell_height` | `f32` | `32` | Uniform 行高。若 \`row\_heights\` 为 null 则所有 row 用此高度（快路径）。 |
| `row_heights` | `?[]const f32` | `null` | 每行高度（px）。长度必须 == row\_count。非 null 时覆盖 \`cell\_height\`。 |
| `width` | `?f32` | `null` | 容器宽度（null = grow） |
| `height` | `?f32` | `null` | 容器高度（null = fit） |
| `scroll_direction` | `ScrollDirection` `.vertical` `.horizontal` `.both` | `.both` | 内层 ScrollArea 的滚动方向；默认保持双轴，调用方可收窄成单轴。 |
| `cell_render_fn` | `?CellRenderFn` | `null` | cell 渲染回调（必填） |
| `cell_render_ctx` | `?*anyopaque` | `null` | — |
| `overscan_rows` | `usize` | `4` | 视口外额外渲染的行数 / 列数，提前加载让滚动不抖动 |
| `overscan_cols` | `usize` | `2` | — |
| `row_window_height_hint` | `?f32` | `null` | 外部行窗口的高度提示（px）。计划用 setExternalRowWindow 驱动行绑定的宿主 应传宿主视口高度：初始 pool 按"窗口能盖住的行数"而非"Grid 自身高度/行数" 估算，否则 height=全内容高的 Grid 会为全部行分配 pool。 |
| `external_row_window` | `?ExternalRowWindow` | `null` | mount 时的初始外部行窗口。不传则首次 updateVisibleCells 按全行绑定 （旧行为），窗口稍后推送时再收缩——会产生一次全量绑定尖峰。 |
| `frozen_rows` | `usize` | `0` | Frozen 行数：表头不随 y 滚动（典型用途 = 1，锁住 header） |
| `frozen_cols` | `usize` | `0` | Frozen 列数：最左 N 列不随 x 滚动 |
| `debug_name` | `[]const u8` | `"Grid"` | Debug / test 用的 component\_name 后缀。默认 "Grid" |

### GridResult

`ui.widgets.mountGrid`

[src/ui/components/grid/mod.zig:42](https://github.com/version-next/zenit/blob/HEAD/src/ui/components/grid/mod.zig#L42)

| Champ | Type | Défaut | Description |
| --- | --- | --- | --- |
| `root` | `*Node` | — | — |
| `state` | `*GridState` | — | — |