---
title: "ScrollArea 组件 — zenit Zig UI"
description: "自绘滚动、滚动条与程序化定位。wheel / trackpad、clamp、momentum、scrollbar、scrollIntoView 和像素对齐共享 state。"
url: https://zenit.z.express/zh/components/scrollarea
language: zh-CN
alternate_en: https://zenit.z.express/components/scrollarea.md
alternate_es: https://zenit.z.express/es/components/scrollarea.md
alternate_ja: https://zenit.z.express/ja/components/scrollarea.md
alternate_ko: https://zenit.z.express/ko/components/scrollarea.md
alternate_fr: https://zenit.z.express/fr/components/scrollarea.md
alternate_de: https://zenit.z.express/de/components/scrollarea.md
project: zenit v0.1.0-alpha (Zig 0.15.2, macOS)
source: https://github.com/version-next/zenit
---

# ScrollArea

`ui.widgets.mountScrollArea`

自绘滚动、滚动条与程序化定位。

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

**BEHAVIOR CONTRACT**

wheel / trackpad、clamp、momentum、scrollbar、scrollIntoView 和像素对齐共享 state。

**RECORDED INTERACTION**

Harness 在内容区域滚动并记录 thumb 位移。

`examples/storybook/stories.zig:2986`

```zig
// ── ScrollArea ──
pub fn buildScrollArea(scope: *ui.Scope, cx: *ui.Cx) anyerror!*ui.Node {
    const a = cx.allocator;
    const sa = try W.mountScrollArea(.{ .width = 320, .height = 320, .direction = .vertical }, scope, cx);
    var i: usize = 0;
    while (i < 40) : (i += 1) {
        var buf: [32]u8 = undefined;
        const txt = try std.fmt.bufPrint(&buf, "Scrollable line {d}", .{i});
        try sa.content.appendChild(a, try ui.text(cx, txt, .{ .font_size = 13, .color = light.color.fg_primary }));
    }
    return sa.container;
}
```

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

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

### ScrollAreaProps

`ui.widgets.mountScrollArea`

[src/ui/components/scroll\_area/mod.zig:55](https://github.com/version-next/zenit/blob/HEAD/src/ui/components/scroll_area/mod.zig#L55)

```zig
fn mountScrollArea(props: ScrollAreaProps, scope: *Scope, cx: *Cx) !ScrollAreaResult
```

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `width` | `?f32` | `null` | — |
| `height` | `?f32` | `null` | — |
| `direction` | `ScrollDirection` `.vertical` `.horizontal` `.both` | `.vertical` | — |
| `content_height` | `?f32` | `null` | — |
| `content_width` | `?f32` | `null` | — |
| `scroll_speed` | `f32` | `1` | 滚动速度乘数（macOS scrollingDelta 已是像素值，默认 1.0） |
| `padding` | `Padding` | `Padding.ZERO` | — |
| `background` | `Color` | `Color.TRANSPARENT` | — |
| `state_id` | `?u64` | `null` | 自定义状态 ID（用于跨实例复用或区分滚动状态） |
| `rubber_band_y` | `bool` | `true` | 垂直方向是否启用 rubber band（果冻回弹）效果 |
| `rubber_band_x` | `bool` | `true` | 水平方向是否启用 rubber band（果冻回弹）效果 |

### ScrollAreaResult

`ui.widgets.mountScrollArea`

[src/ui/components/scroll\_area/mod.zig:74](https://github.com/version-next/zenit/blob/HEAD/src/ui/components/scroll_area/mod.zig#L74)

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `container` | `*Node` | — | — |
| `content` | `*Node` | — | — |
| `state` | `*ScrollState` | — | — |