> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# Stack

布局`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

以一致间距在行或列中排列子元素。

## 何时使用

一维布局与间距不值得单独编写 CSS 时使用 Stack。

**推荐**

- 优先使用 Stack 代替重复 margin。
- 响应式方向使用断点映射。

**避免**

- 具有更丰富语义的布局应使用对应容器。

## 代码演示


### 基础用法
```tsx preview
import { Stack, Tag } from '@rockshin/tao-ui';

function StackExample() {
  return (
    <Stack direction="horizontal" gap="md" align="center">
      <Tag>Design</Tag>
      <Tag>Engineering</Tag>
      <Tag>Research</Tag>
    </Stack>
  );
}

export default StackExample;
```

### 方向、间距与对齐
```tsx preview
import { Stack, Tag } from '@rockshin/tao-ui';

function StackVariants() {
  return (
    <Stack gap="lg">
      <Stack direction="horizontal" gap="sm" align="center">
        <Tag>Small gap</Tag>
        <Tag>Centered</Tag>
      </Stack>
      <Stack direction="horizontal" gap="lg" align="end">
        <Tag>Large gap</Tag>
        <Tag>End aligned</Tag>
      </Stack>
    </Stack>
  );
}

export default StackVariants;
```

### 响应式方向
```tsx preview
import { Button, Stack } from '@rockshin/tao-ui';

function ResponsiveStack() {
  return (
    <Stack
      direction={{ xs: 'vertical', md: 'horizontal' }}
      gap={{ xs: 'sm', md: 'lg' }}
    >
      <Button>Save</Button>
      <Button variant="secondary">Preview</Button>
      <Button variant="ghost">Cancel</Button>
    </Stack>
  );
}

export default ResponsiveStack;
```

### 主轴与交叉轴对齐
用 align 和 root 的 justifyContent 调整子项位置。
```tsx preview
import { Stack, Button } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack
      align="center"
      styles={{
        root: {
          justifyContent: 'space-between',
          minHeight: 100,
          width: '100%',
        },
      }}
    >
      <Button>Start</Button>
      <span>Centered vertically</span>
      <Button>End</Button>
    </Stack>
  );
}
```

### 自然换行
在语义 root 上启用 flexWrap，长工具栏可换行而不撑破页面。
```tsx preview
import { Stack, Button } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack styles={{ root: { flexWrap: 'wrap' } }}>
      {['Overview', 'Members', 'Permissions', 'Billing', 'Settings'].map(
        (item) => (
          <Button key={item}>{item}</Button>
        ),
      )}
    </Stack>
  );
}
```

### 断点方向与间距
窄视口纵向排列，较宽视口切换为横向；可用手机预览对比。
```tsx preview="iframe-follow"
import { Stack, Input, Button } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack
      direction={{ xs: 'vertical', md: 'horizontal' }}
      gap={{ xs: 'sm', md: 'lg' }}
      align="stretch"
    >
      <Input aria-label="Email address" placeholder="name@example.com" />
      <Button variant="primary">Continue</Button>
    </Stack>
  );
}
```

### 嵌套组织布局
外层负责区块间距，内层负责相关操作的排列。
```tsx preview
import { Stack, Button } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical" gap="lg">
      <div>
        <strong>Workspace</strong>
        <p>Invite members and manage access.</p>
      </div>
      <Stack styles={{ root: { flexWrap: 'wrap' } }}>
        <Button variant="primary">Invite member</Button>
        <Button>Manage roles</Button>
      </Stack>
    </Stack>
  );
}
```

## API


### [#](#stack)Stack



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| direction | Flex direction. Accepts a breakpoint map, e.g.
`direction={{ xs: 'vertical', md: 'horizontal' }}` — the largest matching
breakpoint wins (SSR/first render falls back to the plain default). | `TaoResponsiveValue<StackDirection> | undefined` | `vertical` |
| className | 节点类名 | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |

