# @fiscozen/container 中文文档

规范地址：https://npmcn.com/package/%40fiscozen/container/

版本：0\.5\.2
npm 元数据更新时间：2026-09-07T07:16:41.076Z
中文译文更新时间：2026-11-14T20:22:31.956Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fiscozen/container
原文对照：https://npmcn.com/package/%40fiscozen/container/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：103 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：tailwindcss ^3\.4\.1，vue ^3\.4\.13
- 首次发布：2025-09-22T12:35:37.779Z
- 最新版本发布：2026-09-07T07:16:40.876Z
- 近 30 天下载量：25827（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 6 个）

## 中文简介

设计系统集装箱部分

## 安装

```sh
npm install @fiscozen/container
```

也可以使用：`pnpm add @fiscozen/container`、`yarn add @fiscozen/container`、`bun add @fiscozen/container`

## README

# @fiscozen/ 容器

灵活布局组件,用于组织具有可控间隔的内容. 支持纵向取向和水平取向,并有自定义的缺口大小.

## 特征

-   纵向和横向布局方向
-   横向容器的布局变体(`expand-first`, (中文(简体) ), `expand-all`, (中文(简体) ), `expand-equal`, (中文(简体) ), `space-between`, (中文(简体) ), `expand-last`(中文(简体) )
-   通过横轴对齐 `alignItems` (开始/中心/结束/拉伸/基线)
-   自定义的空格大小( E)`none` 编号 : `xs` 编号 : `sm` 编号 : `base` 编号 : `lg`)带有单独的主比分
-   不同间隔尺度的主要和部分容器变体
-   垂直模式相接段落之间的特殊间隔
-   用于语义标记的灵活 HTML 标签渲染

## 安装

```bash
npm install @fiscozen/container
```

## 基本用途

### 垂直布局( 默认)

```vue
<script setup>
import { FzContainer } from '@fiscozen/container'
</script>

<template>
  <FzContainer main>
    <FzContainer>
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </FzContainer>

    <FzContainer>
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </FzContainer>
  </FzContainer>
</template>
```

### 水平布局

```vue
<template>
  <FzContainer horizontal>
    <button>Action 1</button>
    <button>Action 2</button>
    <button>Action 3</button>
  </FzContainer>
</template>
```

## 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `main` | `boolean` | `false` | 若为 `true`,使用主容器间距(页平面相距较大) |
| `gap` | `'sm' | 'base' | 'lg'` (当 `main={true}`(中文(简体) )  
`'none' | 'xs' | 'sm' | 'base' | 'lg'` (当 `main={false}`(中文(简体) ) | `'base'` | 元素之间的间隔大小 。 可用值取决于容器类型 |
| `horizontal` | `boolean` | `false` | 若为 `true`,元素水平对齐。 否则,垂直( 默认) |
| `layout` | `'default' | 'expand-first' | 'expand-all' | 'expand-equal' | 'space-between' | 'expand-last'` | `'default'` | 水平容器的布局行为(控制子元素的扩展方式). 仅适用于下列情况: `horizontal` 实值 `true` |
| `alignItems` | `'start' | 'center' | 'end' | 'stretch' | 'baseline'` | `'stretch'` 对于垂直, `'center'` 水平 | 交叉轴上的儿童元素对齐. 在垂直容器中:水平对齐(左/中/右). 横向容器:纵向对接(上/中/下) |
| `tag` | `string` | `'div'` | 用于容器元素的 HTML 标签 |

## 差距大小

该组件使用CSS自定义属性来进行整个设计系统的一致间隔.

### 主要集装箱`main={true}`(中文(简体) )

| 大小 | CSS 变量 | 数值 |
| --- | --- | --- |
| `sm` | `--main-content-sm` | 32px 密码 |
| `base` | `--main-content-base` | 48px 坐标 |
| `lg` | `--main-content-lg` | 64px (英语) |

### 集装箱`main={false}` 或违约)

| 大小 | CSS 变量 | 数值 |
| --- | --- | --- |
| `none` | `--section-content-none` | 0px (单位:秒) |
| `xs` | `--section-content-xs` | 8个px |
| `sm` | `--section-content-sm` | 16px 时 |
| `base` | `--section-content-base` | 24px (英语) |
| `lg` | `--section-content-lg` | 32px 密码 |

**主要集装箱** 用于页面级别部分,并使用更大的间隔值. **部门集装箱** 用于各节内的内容,并使用较小的间隔值,另加 `none` 财务报告和审定财务报表 `xs` 选项.

## 方向行为

### 垂直( 默认)

-   元素垂直堆叠
-   垂直应用元素间的差距
-   相接段落的特殊间隔`p + p`用于改进可读性
-   大多数使用的默认布局
-   默认对齐 : `alignItems="stretch"` (要素扩展至全宽)

### 水平

-   元素在一行中水平对齐
-   横向应用元素间的差距
-   不包装——元素保持单行
-   想要动作按钮、内置控制或水平导航
-   通过 `layout` 道具(见下文布局行为部分)
-   默认对齐 : `alignItems="center"` (纵向中心)

## 布局行为( 仅Horizontal)

这个 `layout` 道具控制儿童元素如何扩张,以在水平容器中填充可用的空间. 此道具只在 `horizontal` 实值 `true`。 。 。 .

### 可用布局

| 版式 | 说明 |
| --- | --- |
| `default` | 所有元素都保持其自然大小(`flex-grow: 0`) (中文(简体) ). 这是默认行为. |
| `expand-first` | 第一个要素扩展为填补可用的空间(`flex-grow: 1`),而其他元素则保持其自然大小. |
| `expand-all` | 所有要素都扩大了(`flex-grow: 1`) 平等分享额外空间。 最后宽度仍然取决于每个孩子的内在内容大小——使用 `expand-equal` 当列必须具有相同的宽度,而无论内容如何. |
| `expand-equal` | 所有儿童都获得相同的宽度(CSS Grid 与 `grid-auto-columns: minmax(0, 1fr)`),忽略了内在内容大小. 用于类似网格的布局,列必须横行对齐. |
| `space-between` | 元素在它们之间分配空间(`justify-content: space-between`) (中文(简体) ). 元素保持其自然体积. |
| `expand-last` | 最后一个元素扩展以填补可用的空间( :`flex-grow: 1`),而其他元素则保持其自然大小. |

### 何时使用每个布局

**`default`**: 当所有元素都应保持其自然大小时使用. 对按钮组、导航项目或元素不应生长的任何水平列表都有好处.

**`expand-first`**: 当您想要第一个元素占用所有剩余空间时使用。 用于 `[content | actions]` 工具栏.

**`expand-all`**: 当您想要所有元素都增长并吸收额外的水平空间时使用(对于具有可比较标签长度的按钮组是好的). 请注意,最终宽度仍然取决于每个孩子的内容——对于真正相同的宽度,使用 `expand-equal`。 。 。 .

**`expand-equal`**: 当列无论内容如何都必须有相同的宽度时使用(在矩阵中的卡片,等式工具栏部分,仪表板平板砖). 取舍:具有很长的不可破碎内容的儿童可能会视而不见地超越其位置.

**`space-between`**: 当想要元素保持其自然大小但被分布到可用的空间时使用.

**`expand-last`**: 当您想要占用所有剩余空间时使用。 用于 `[actions | content]` 右侧区域应扩展的图案.

## 对齐项目行为

这个 `alignItems` 道具控制儿童元素如何与 **横轴** (与主轴相接.

### 垂直容器

控件 **水平对齐** 要点:

**`stretch`** (默认):填充容器宽度的元素拉长 **`start`**: 元素向左对齐 **`center`**: 元素横向居中 **`end`**: 元素与右边对齐 **`baseline`**: 元素与其文本基线一致

### 水平容器

控件 **垂直对齐** 要点:

**`start`**: 元素对齐到顶端 **`center`** (默认):元素垂直居中 **`end`**: 元素对齐到下方 **`stretch`**: 填充容器高度的元素拉伸 **`baseline`**: 元素与其文本基线一致(对文本有用)

## 实例

### 有不同缺口的嵌入式集装箱

```vue
<template>
  <FzContainer main gap="lg">
    <h1>Page Title</h1>
    
    <FzContainer>
      <h2>Section Title</h2>
      <p>Content paragraph 1</p>
      <p>Content paragraph 2</p>
    </FzContainer>
    
    <FzContainer gap="sm">
      <label>Form Label</label>
      <input type="text" />
      <span>Helper text</span>
    </FzContainer>
  </FzContainer>
</template>
```

### 水平按钮组

```vue
<template>
  <FzContainer horizontal gap="sm">
    <button>Cancel</button>
    <button>Save Draft</button>
    <button>Publish</button>
  </FzContainer>
</template>
```

### 自定义 HTML 标记

```vue
<template>
  <FzContainer tag="section" main>
    <h1>Section Content</h1>
    <p>This container renders as a section element</p>
  </FzContainer>
</template>
```

### 布局: 先展开( 任务列表)

```vue
<template>
  <FzContainer gap="sm">
    <FzContainer horizontal layout="expand-first" gap="base">
      <FzContainer gap="sm">
        <p>Task name that can be very long</p>
        <p>Task description that will expand to fill available space</p>
      </FzContainer>
      <button>Complete</button>
    </FzContainer>
    
    <FzContainer horizontal layout="expand-first" gap="base">
      <FzContainer gap="sm">
        <p>Another task</p>
        <p>With another description</p>
      </FzContainer>
      <button>Complete</button>
    </FzContainer>
  </FzContainer>
</template>
```

### 布局: 先展开( 表格动作)

```vue
<template>
  <FzContainer gap="base">
    <input type="text" placeholder="Form field..." />
    <input type="text" placeholder="Another field..." />
    
    <!-- Actions aligned to the right -->
    <FzContainer horizontal layout="expand-first" gap="base">
      <FzContainer></FzContainer>
      <FzContainer horizontal gap="sm">
        <button>Cancel</button>
        <button>Save</button>
      </FzContainer>
    </FzContainer>
  </FzContainer>
</template>
```

### 布局: 全部展开

```vue
<template>
  <FzContainer horizontal layout="expand-all" gap="base">
    <button>Button 1</button>
    <button>Button 2</button>
    <button>Button 3</button>
  </FzContainer>
</template>
```

### 布局: 全部展开

```vue
<template>
  <FzContainer horizontal layout="expand-all" gap="lg">
    <div class="card">
      <h3>Card 1</h3>
      <p>Content here</p>
    </div>
    <div class="card">
      <h3>Card 2</h3>
      <p>Content here</p>
    </div>
    <div class="card">
      <h3>Card 3</h3>
      <p>Content here</p>
    </div>
  </FzContainer>
</template>
```

### 布局: 展开等同

```vue
<template>
  <!-- All three buttons end up with identical widths even with asymmetric labels -->
  <FzContainer horizontal layout="expand-equal" gap="base">
    <button>OK</button>
    <button>Salva e continua</button>
    <button>Annulla</button>
  </FzContainer>
</template>
```

```vue
<template>
  <!-- Grid-like rows where columns must align across rows -->
  <FzContainer gap="sm">
    <FzContainer horizontal layout="expand-equal" gap="base">
      <div class="tile">Tile A</div>
      <div class="tile">Tile B with a much longer title</div>
      <div class="tile">C</div>
    </FzContainer>
    <FzContainer horizontal layout="expand-equal" gap="base">
      <div class="tile">Tile D</div>
      <div class="tile">Tile E</div>
      <div class="tile">Tile F</div>
    </FzContainer>
  </FzContainer>
</template>
```

#### 相同的宽度和相同的高度

组合 `layout="expand-equal"` 与 `alignItems="stretch"` 即使儿童的内容内在高度不同,也要使儿童横行的宽度和高度一致。 这是FzContainer的"克线"配方.

```vue
<template>
  <FzContainer horizontal layout="expand-equal" alignItems="stretch" gap="base">
    <div class="tile">Short tile</div>
    <div class="tile">Medium tile<br/>with two lines</div>
    <div class="tile">Tall tile<br/>with three<br/>lines of content</div>
  </FzContainer>
</template>
```

全部三块瓷砖最终都有相同的宽度(从 `expand-equal`和相同的高度(从 `alignItems="stretch"`,与最高的孩子匹配.

### 布局: 间距

```vue
<template>
  <FzContainer horizontal layout="space-between" gap="base">
    <div class="logo">Logo</div>
    <nav>
      <FzContainer horizontal gap="sm">
        <a href="#">Home</a>
        <a href="#">About</a>
        <a href="#">Contact</a>
      </FzContainer>
    </nav>
  </FzContainer>
</template>
```

### 布局: 间距

```vue
<template>
  <FzContainer horizontal layout="space-between" gap="base">
    <FzContainer gap="xs">
      <h1>Page Title</h1>
      <p>Subtitle or description</p>
    </FzContainer>
    <FzContainer horizontal gap="sm">
      <button>Cancel</button>
      <button>Save</button>
    </FzContainer>
  </FzContainer>
</template>
```

### 布局: 最后一次展开( 任务列表)

```vue
<template>
  <FzContainer gap="sm">
    <FzContainer horizontal layout="expand-last" gap="base">
      <button>Complete</button>
      <FzContainer gap="sm">
        <p>Task name that can be very long</p>
        <p>Task description that will expand to fill available space</p>
      </FzContainer>
    </FzContainer>

    <FzContainer horizontal layout="expand-last" gap="base">
      <button>Complete</button>
      <FzContainer gap="sm">
        <p>Another task</p>
        <p>With another description</p>
      </FzContainer>
    </FzContainer>
  </FzContainer>
</template>
```

### 布局: 最后一次展开( 表格动作)

```vue
<template>
  <FzContainer gap="base">
    <input type="text" placeholder="Form field..." />
    <input type="text" placeholder="Another field..." />

    <!-- Actions aligned to the left -->
    <FzContainer horizontal layout="expand-last" gap="base">
      <FzContainer horizontal gap="sm">
        <button>Cancel</button>
        <button>Save</button>
      </FzContainer>
      <FzContainer></FzContainer>
    </FzContainer>
  </FzContainer>
</template>
```

### 对齐项目:与中心对齐的垂直容器

```vue
<template>
  <FzContainer alignItems="center" gap="base">
    <h1>Centered Title</h1>
    <p>Centered paragraph</p>
    <button>Centered button</button>
  </FzContainer>
</template>
```

### 对齐项目: 垂直容器对齐

```vue
<template>
  <FzContainer alignItems="end" gap="sm">
    <p>Amount: €100</p>
    <p>Tax: €22</p>
    <p>Total: €122</p>
  </FzContainer>
</template>
```

### 对齐项目:水平容器与顶部对齐

```vue
<template>
  <FzContainer horizontal alignItems="start" gap="base">
    <img src="icon.png" style="height: 40px" />
    <div>
      <h3>Title</h3>
      <p>Description</p>
    </div>
  </FzContainer>
</template>
```

### 对齐项目:水平容器与基线对齐

```vue
<template>
  <FzContainer horizontal alignItems="baseline" gap="base">
    <span style="font-size: 0.75rem">Small text</span>
    <span style="font-size: 1rem">Medium text</span>
    <span style="font-size: 1.5rem">Large text</span>
  </FzContainer>
</template>
```

## 字法笔记

在使用垂直方向时,组件在相接的段落元素之间适用特殊间隔(`<p>`提高可读性。 此间距由 `--paragraph-gap` CSS自定义属性并覆盖默认的空白,以便更好的打字.

这种特殊间隔不适用于横向方向,因为横向段落布局并不常见.

## 无障碍

该组件使 HTML 语义化,并可使用 `tag` 使用适当的语义元素的道具(例如, `form`)基于您的内容结构.

## 常见问题

### @fiscozen/container 是什么？

设计系统集装箱部分

### 如何安装 @fiscozen/container？

在项目目录运行 npm install @fiscozen/container，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：tailwindcss（^3\.4\.1）、vue（^3\.4\.13）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fiscozen/container 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fiscozen\_\_container 是否存在。

### @fiscozen/container 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fiscozen/container 可以商用吗？

@fiscozen/container 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fiscozen/container 的下载量有多少？

根据 npm 官方下载统计，@fiscozen/container 在 2026/10/15 – 2026/11/13 这 30 天内被下载 25,827 次，日均约 861 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fiscozen/container 还在维护吗？

最新版本 0\.5\.2 发布于 2026/09/07（2 个月前）；至今共发布 11 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/09/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。