# @fiscozen/layout 中文文档

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

版本：1\.4\.6
npm 元数据更新时间：2026-10-23T08:35:13.448Z
中文译文更新时间：2026-11-14T20:47:51.787Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：541 kB，66 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- peer 依赖：vue ^3\.4\.13，tailwindcss ^3\.4\.1
- 首次发布：2024-11-05T16:13:11.266Z
- 最新版本发布：2026-10-23T08:35:12.978Z
- 近 30 天下载量：2622（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 18 个）

## 中文简介

设计系统布局组件

## 安装

```sh
npm install @fiscozen/layout
```

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

## README

# @fiscozen/放电

Vue 3应用的布局构件,由原子设计层组织.

## `FzLayout` ——网格原始(组织)

基于网格的布局组件提供多种布局变体(例如. `oneColumn`, (中文(简体) ), `twoColumns`, (中文(简体) ), `multipleAreas`, (中文(简体) ), `threeColumns`(d) 涵盖共同 页面结构。 默认情况下铺设; 选择退出 `disablePadding` 供血满地的地区使用.

## 地区(山区)

仅以页为单位的页块的演示文稿 模板。 区域建设 **刚刚来** 与他们的第一模板 而不是作为投机图书馆.

### `FzLayoutMain`

"主"内容区域. 生成语义 `<main>` 地标和集权 区域一级的关切.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `as` | `'main' | 'div'` | `'main'` | 该区域形成的要素是: 覆盖到 `'div'` 当它不是页面 `main`。 。 。 . |
| `align` | `'stretch' | 'top' | 'center'` | `'stretch'` | 区域内的内容调整. |
| `safeArea` | `boolean` | `false` | 由设备安全区域内设( S)`env(safe-area-inset-*)`(c) 指针/家庭指标. |

### `FzLayoutHeader` • 妇女 `FzLayoutAside` • 妇女 `FzLayoutFooter`

用于上行的细微语义包装( S)`<header>` 横幅),互补 (单位:千美元)`<aside>`)和页脚(`<footer>` 内容info)区域. 他们使 地标元素和稳定的类钩; 特定布局大小/铺设 由编译模板应用。 每一个都接受一个 `as` 道具 — 键入 其标志性要素或 `'div'` ——当页面不能覆盖时,要覆盖元素 两次揭露那个地标.

### `FzLayoutBottomBar`

粘性底部动作栏区域. 按模板放在主机内 内容栏, 它 `position: sticky`s 到页面的视图下方 卷轴,在流量中保留自己的高度(因此空条倒塌,没有) 需要手动打底板)。 它没有背景,没有垫子 安全区域设置: 条状内容涂上表面, 所以它贴上 `env(safe-area-inset-bottom)` 本身及其背景到达设备边缘. 集装箱是 `pointer-events: none` 所以水龙头会穿过空地; 其直接子女再次互动。 它不需要道具 并暴露它的 根元素为 `el` 所以一个模板可以把它用作下巴的远程传送目标.

## 页面模板

完整页面, 仅选择演示文稿 `<router-view>` 级别。 他们 渲染帧 + 区域并曝光命名的槽; 应用程序以 它自己的生物体(导航,聊天,标题,动作),拥有所有逻辑.

### `FzBlankTemplate`

无铬的全血模板——单一全高含量区域 没有别的了。 用于认证/登录屏幕和建立自己的独立工具 自成一体的UI. 它拥有一个全高的根(`min-h-dvh`),所以它确实如此 **没有** 依赖于全球应用 `#app { height: 100% }` 编号 : `overflow-y: auto` CSS 状态 现相.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `align` | `'center' | 'top'` | `'center'` | 内容坐落在全高页内的地方. |

```vue
<template>
  <FzBlankTemplate align="center">
    <LoginCard />
  </FzBlankTemplate>
</template>
```

### `FzFocusTemplate`

引导流动(入职)和认证的分流减少流量模板 屏幕。 中心主区域,可选由 `topbar`, (中文(简体) ), `aside` 财务报告和审定财务报表 `footer` (每个项目只提供其槽 `aside` 下方的堆栈 在狭长的取景口上的内容 坐在旁边 `lg` 起来 拥有 a 全高根并应用安全区域内设.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `chrome` | `'card' | 'flat'` | `'card'` | 内容框架. `card` = 包含最大宽度的卡; `flat` =满血 (秋季). |

槽数 : `topbar`,默认值(中心内容), `aside`, (中文(简体) ), `footer`。 。 。 .

```vue
<template>
  <FzFocusTemplate chrome="card">
    <template #topbar><OnboardingTopBar /></template>
    <OnboardingStep />
    <template #aside><SupportChatPanel /></template>
  </FzFocusTemplate>
</template>
```

### `FzListTemplate`

后台列表-页面布局——列表页面的反复出现形状:可选 全宽 `banner` (警报,动作卡),可选 `filters` 铁路,一个 选项 `header` 工具栏(标题/搜索/行动)和列表内容本身 (一般为: `FzTable`) (中文(简体) ). 每一区域只有在提供其时间档时才产生.

与上面的模板不同,这是 **页面内容** 模板设计为 在弹壳的主要区域内制造,所以 **没有** 强制视图高度 或应用 root- safe-rea 设置—— shell 拥有滚动容器和设备 安全区域。 它构成区域分子(`FzLayoutAside` + 键 `FzLayoutMain`(中文(简体) ) 用文档滚动而不是 `FzLayout leftShoulder`,哪些力量 `100vh` 移动轨道和独立的每个区域滚动.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `filtersPosition` | `'left' | 'top'` | `'left'` | `left` = 在内容旁的固定宽度铁路 `md` 上行(上行移动); `top` =全线行. |
| `filtersLabel` | `string` | —— 说 | 可访问名称( N)`aria-label`用于 `filters` 铁路 `complementary` 标志性。 当页面暴露出不止一个互补区域(如自有外壳入巢)时设定,因此屏幕阅读器用户可以将其区分开来. |
| `mainAs` | `'main' | 'div'` | `'main'` | 内容区域是 。 设定为 `'div'` 当在已经拥有的外壳内筑巢 `<main>`。 。 。 . |

槽数 : `banner`, (中文(简体) ), `filters`, (中文(简体) ), `header`,默认值(列表内容).

```vue
<template>
  <FzListTemplate filters-position="left">
    <template #banner><OutOfPeriodAlert /></template>
    <template #filters><VatDeclarationFilters /></template>
    <template #header><ListTitleAndSearch /></template>
    <FzTable v-bind="tableProps" />
  </FzListTemplate>
</template>
```

### `FzDetailTemplate`

后台详细页面布局——兄弟关系 `FzListTemplate` (LIB-2694) (英语). 何处 列表页面对 a _过滤器_ 带有表格的栏杆,详细页面对一持久 `sidebar` 简易/折叠铁路(记录的身份、状况、元和行动) 与记录的内容(通常为 `FzTabs`编号 :`FzCard`页:1 这也暴露了一种 可选全宽 `banner` (页数提醒)和可选 `toolbar` (标题/行动). 每个区域只有在提供槽后才能制作;以上简易铁路堆放 尸体在狭长的取景口上 坐在旁边 `md` 起来.

喜欢 `FzListTemplate`,这是一个 **页面内容** 用于渲染的模板 在炮弹的主要区域,所以它确实 **没有** 强迫视图高度或应用 root- safe-rea insets——贝壳拥有滚动容器和装置安全区域. 它构成区域分子(`FzLayoutAside` + 键 `FzLayoutMain`)带有文档 滚动而不是 `FzLayout leftShoulder`,哪些力量 `100vh` 移动轨道和 独立区域卷轴.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `sidebarLabel` | `string` | —— 说 | 可访问名称( N)`aria-label`用于 `sidebar`是因为 `complementary` 标志性。 当页面暴露出不止一个互补区域时设定(例如用自己的外壳嵌入),所以屏幕读者将它们分解. |
| `mainAs` | `'main' | 'div'` | `'main'` | 内容区域是 。 设定为 `'div'` 当在已经拥有的外壳内筑巢 `<main>`。 。 。 . |

槽数 : `banner`, (中文(简体) ), `sidebar`, (中文(简体) ), `toolbar`,默认值(细节正文). 这个 `toolbar` 地区是一个平坦的容器, **没有** (单位:千美元) `<header>`/班纳地标-外壳 拥有页面横幅.

```vue
<template>
  <FzDetailTemplate sidebar-label="Riepilogo dichiarazione">
    <template #banner><NotYetSentAlert /></template>
    <template #sidebar><VatDeclarationSummary /></template>
    <template #toolbar><DetailTitleAndActions /></template>
    <FzTabs>
      <FzTab title="Dichiarazione">…</FzTab>
      <FzTab title="F24">…</FzTab>
    </FzTabs>
  </FzDetailTemplate>
</template>
```

**属性转发 .** `FzBlankTemplate`单根 _实值_ 联合国 `<main>` 区域,因此通过属性`aria-label`, (中文(简体) ), `id`, (中文(简体) ), `data-*`着陆在那上面 `<main>`。 。 。 . `FzFocusTemplate`, (中文(简体) ), `FzListTemplate` 财务报告和审定财务报表 `FzDetailTemplate` 有个 非地标容器 `<div>` 作为他们的根,所以倒下 属性土地在 那个集装箱, **没有** 在内心 `<main>` - 如果 `main` 需要无障碍名称.

### `FzAppTemplate`

持久导航应用外壳(前台标准布局). 框架 a 持久性 `nav`,可选粘贴 `header`,主要内容,可选 辅助 `aside`,可选粘性底层动作栏和可选 `footer`。从 `desktop` 断点(1200px)上方,导航为左粘度 栏杆和边上有一个粘着的右面板——它们的宽度沿着 **已注射** 内容,绝不是模板。 这个 **导航持续** (移动顶级区域); 输入式导航,例如. [`FzNavbar`](https://npmcn.com/package/%40fiscozen/navbar) 拥有自己的反应能力 和汉堡,所以模板 使没有导航抽屉。 下面 导航区域是 `sticky` 时间 `z-10`,粘着的盒子就是堆放 上下文,不管其z-index:覆盖所注入的导航打开(全屏) 菜单)不能高于后一个 `z-10` 从里面的铬,所以电传到 `body` 在抽屉一级`z-30`) (中文(简体) ). 只有 **让开** 在断点下方倒塌,进入一个模式抽屉(`role="dialog"` + 键 `aria-modal` +焦点陷阱 + Escape-to-close). 拥有全高根并适用 其粘稠的染色体有定向安全区域被套入.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `hasAside` | `boolean` | `false` | 将辅助设备放在一边(桌面面板/移动抽屉). |
| `hasBottomBar` | `boolean` | `true` | 将粘稠的下巴区域引入,并提供其远程传送目标. |
| `chrome` | `'card' | 'flat'` | `'card'` | 内容框架. `card` \* 含有白卡; `flat` =满出血. |
| `contentWidth` | `'standard' | 'wide' | 'full'` | `'standard'` | 主内容栏宽度( 替换应用程序的旧 `wideLayout`) (中文(简体) ). |
| `asideLabel` | `string` | —— 说 | 当它是一个模式抽屉(移动)时,可以调取它的名称. |

槽数 : `nav`, (中文(简体) ), `header`,默认(内容), `aside`, (中文(简体) ), `bottomBar`, (中文(简体) ), `footer`编辑 `nav`, (中文(简体) ), `header` 财务报告和审定财务报表 `aside` 槽接收响应的切换道具 `{ isDesktop, asideOpen, toggleAside }`。 。 。 .

```vue
<template>
  <FzAppTemplate has-aside class="bg-[#f7f6f3]">
    <!-- FzNavbar renders its own rail (desktop) / bar + hamburger (mobile) -->
    <template #nav><AppNavigation /></template>
    <template #header="{ toggleAside }">
      <PageTitleBar @help="toggleAside(true)" />
    </template>
    <RouterView />
    <template #aside><SupportChatPanel /></template>
  </FzAppTemplate>
</template>
```

#### 底巴远程运输合同`FZ_BOTTOM_BAR_TARGET`(中文(简体) )

`FzAppTemplate` `provide()`s 其下行区域元素 `FZ_BOTTOM_BAR_TARGET`,所以深页组件可以在 shell level 没有应用程序拥有魔法 DOM ID. 模板拥有该栏 几何( 它自动对齐内容列); 页面拥有 内容,包括其底层安全区设置(见 `FzLayoutBottomBar`) (中文(简体) ). 警卫 页:1 `null` 案件 - 这意味着没有 `FzAppTemplate` 祖师相.

```ts
import { inject } from 'vue'
import { FZ_BOTTOM_BAR_TARGET } from '@fiscozen/layout'

const bottomBarTarget = inject(FZ_BOTTOM_BAR_TARGET, null)
// <Teleport v-if="bottomBarTarget" :to="bottomBarTarget" defer> …actions… </Teleport>
```

见 [`docs/RFC/layout/bottom-bar-adr.md`](https://npmcn.com/package/docs/RFC/layout/bottom-bar-adr.md) 以备决定记录.

### `FzFrameTemplate`

这个 **后台应用程序框架**: 持久图标 `nav` 铁栏杆,一丝不挂 应用程序级 `header` 工具栏、页面和可选400px `aside` 持有工具 随处可见。 页面布局巢 _内部_ 默认位置.

**它存在的原因是高度契约,而不是铬.** 每一个 贝壳在这里 `min-h-dvh` + 文档滚动 – 具有 _无限期_ 高度,其中a `fills-parent` 版式 ([`FzThreeColumnsTemplate`](https://npmcn.com/package/%40fiscozen/layout/#readme-page-templates)(中文(简体) ) 倒数倒数为零,从不滚动区域。 这个外壳反转模型: 根为 `h-dvh` 财务报告和审定财务报表 **剪辑**,以及 `contentHeight` 选择与内容订约的 区域提议.

| `contentHeight` | 区域 | 对于 |
| --- | --- | --- |
| `scroll` _(默认)_ | 是应用程序的 **单滚动容器** ——文档滚动从窗口移动到其中 | 以一页显示并滚动的页面: `FzListTemplate`, (中文(简体) ), `FzDetailTemplate`,以文档滚动方式写入的页面 |
| `bounded` | 有一个 **确定高度和夹片** | 填充框架并滚动它自己的区域的一页: `FzThreeColumnsTemplate` |

因为开关是每页的,所以迁移是递增的:一个页面选择使用 `bounded` 当它被移植的时候,其他的一页都没有被移动.

框架是下面一栏 `lg` (1024px)及其上方一行,为CSS. `lg` 而不是现在 `desktop` 1200px) 断点 `FzAppTemplate` 使用,因为 _注入导航_ 开关时间 `lg`: 保存在左一列过去, [`FzNavbar`](https://npmcn.com/package/%40fiscozen/navbar)紧凑的条条收缩到一个树枝上.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `contentHeight` | `'scroll' | 'bounded'` | `'scroll'` | 高度合同交给内容区(见上文). |
| `chrome` | `'card' | 'flat'` | `'card'` | `card` = 嵌入的白色表面; `flat` =满出血. |
| `background` | `'page' | 'transparent'` | `'page'` | 铬后页背景. |
| `hasAside` | `boolean` | `false` | 调整工具面板区域. |
| `navLabel` | `string` | —— 说 | 可读名称 `<nav>` 标志性. |
| `asideLabel` | `string` | —— 说 | 侧面的无障碍名称 `complementary` 标志性. |

槽数 : `nav`, (中文(简体) ), `header`,默认值(页), `aside`。铬槽接收 `{ isDesktop, asideOpen, toggleAside }`; 面板的开口状态是 `v-model:asideOpen`。 。 。 .

`chrome` 是故意的,这是故意的 **直肠** 改为 `contentHeight`,没有一个"正在迁移" 旗帜: 移植到 `FzListTemplate` 仍然随区域滚动(`scroll`(中文(简体) ) 但应让框架拥有其容器(`card`) (中文(简体) ). 绘制自己的页面 集装箱停留 `flat`,或两个带有一行页面背景的白盒堆栈 他们之间.

```vue
<template>
  <FzFrameTemplate
    v-model:aside-open="toolsOpen"
    :content-height="route.meta.contentHeight ?? 'scroll'"
    :chrome="route.meta.chrome ?? 'flat'"
    has-aside
    nav-label="Navigazione principale"
    aside-label="Strumenti"
  >
    <template #nav><AppNavigation /></template>
    <template #header="{ asideOpen, toggleAside }">
      <FrameToolbar :aside-open="asideOpen" @toggle-tools="toggleAside()" />
    </template>
    <RouterView />
    <template #aside="{ toggleAside }">
      <ToolsPanel @close="toggleAside(false)" />
    </template>
  </FzFrameTemplate>
</template>
```

工具面板是一个 **页面的兄弟关系**不是每一页都能做的 所以 里面装有的东西 保持整个导航状态 没有全球储存 它被隐藏在 `v-show` 而不是卸载,所以它保持状态 过近/开放.

#### 页面滚动合同`FZ_PAGE_SCROLL_TARGET`(中文(简体) )

下 `contentHeight="scroll"` 页:1 **窗口不再滚动**: 内容 地区确实如此。 这么说吧 `window.scrollTo(0, 0)` 成为无操作,并浏览器滚动 返回/向前恢复——只恢复文档滚动器—— 停止到达页面。 壳 `provide()`s 区域元素使应用程序能够 滚动页面并将其路由器接线 `scrollBehavior` 反对它。 守卫 `null` 例:指没有贝壳祖先拥有卷轴容器.

```ts
import { inject } from 'vue'
import { FZ_PAGE_SCROLL_TARGET } from '@fiscozen/layout'

const pageScroll = inject(FZ_PAGE_SCROLL_TARGET, null)
// pageScroll?.value?.scrollTo({ top: 0 })
```

这两项合同都提供了这一要素,但仅提供了 _滚动_ 下级 `scroll`数字 : 下级 `bounded` 区域剪辑和嵌入式布局 滚动自己的区域,所以 联合国 `scrollTop` 保留0. `scrollIntoView` 呼叫站点无论哪种方式都不受影响—— 他们走到最近的可滚动的祖先.

#### 关于"尾风"预飞的说明

这外壳是故意的 **独立于尾风飞行前**和任何东西 增加的内容必须如此: `border-solid` 财务报告和审定财务报表 `box-border` 明确而不是依赖重置。 后台瞄准镜 `.twp` 类,而将该类放在页槽的祖先上将适用 一次重置成数百个遗留部件 应用程序显示 `twp` 独自一人 位置内容代替.

见 [`docs/RFC/layout/frame-shell-promotion.md`](https://npmcn.com/package/docs/RFC/layout/frame-shell-promotion.md) 以备决定记录.

## 布局显示( E)`layouts.json`(中文(简体) )

除了组件, 本套件还发布 [`layouts.json`](https://npmcn.com/package/%40fiscozen/layout/layouts.json): 每种布局的机器可读描述 它输出——每一页是什么形状的,它与它混淆,它是如何形成的 确定它的高度, 哪些宿主被证实在其中的巢穴 它的能力是无法达到的,根据一种只作曲的造型政策.

由 **代理设计** 插件在会话开始时读取 回答任何设计实施的第一个问题—— _哪个布局应该 此页面使用 ?_ ——所以在此添加的布局可以选择在 org 上 任何消耗性还款都没有变化.

它的合约是JSON Schema [`ds-layouts.schema.json`](https://npmcn.com/package/%40fiscozen/layout/ds-layouts.schema.json),哪个 `layouts.json` 参考文献 `$schema`。 。 。 . `src/__tests__/layouts.manifest.spec.ts` 验证 与真主同受刑罚的 `src/index.ts` 和与 `Fz…Slots` 类型。 插件拥有计划; 这里的复制件是 逐字可以检测出漂移 见 `CLAUDE.md` 此软件包之前 更改任一文件.

## 稳定和贡献政策

这个包裹有意将网格原始,区域分子,和 前台和后台应用程序依赖于 撞倒它 撞倒它 撞倒它 **独立**使公众表面共享, 跨repo合同(RFC 第10节):

-   **对已公布组件的更改必须是添加剂.** 新建可选道具( 有 默认、新插槽和新组件都很好, 插槽或导出,使所需的可选道具,或缩小道具 已接受的值为 **断开** 并且不允许没有协调的 前台+后台迁移.
-   **取出前作折旧.** 标记旧 API `@deprecated` 在未成年人中 释放,保持它的工作, 并只去除它在随后的主修.
-   每艘变更船都有一个正确起落平分的变更集;运行 `pnpm release:check:pending` 在发布前预览级联.

见 [`docs/RFC/layout/page-templates-extraction.md`](https://npmcn.com/package/docs/RFC/layout/page-templates-extraction.md) §10作为理由——这是项目困难的制约因素,而不是偏好.

## 常见问题

### @fiscozen/layout 是什么？

设计系统布局组件

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

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

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

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

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

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

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

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

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

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

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

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