@fiscozen/放电

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

FzLayout ——网格原始(组织)

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

地区(山区)

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

FzLayoutMain

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

FzLayoutHeader • 妇女 FzLayoutAside • 妇女 FzLayoutFooter

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

FzLayoutBottomBar

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

页面模板

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

FzBlankTemplate

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

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

FzFocusTemplate

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

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

<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 移动轨道和独立的每个区域滚动.

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

<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 移动轨道和 独立区域卷轴.

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

<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 拥有自己的反应能力 和汉堡,所以模板 使没有导航抽屉。 下面 导航区域是 sticky 时间 z-10,粘着的盒子就是堆放 上下文,不管其z-index:覆盖所注入的导航打开(全屏) 菜单)不能高于后一个 z-10 从里面的铬,所以电传到 body 在抽屉一级z-30) (中文(简体) ). 只有 让开 在断点下方倒塌,进入一个模式抽屉(role="dialog" + 键 aria-modal +焦点陷阱 + Escape-to-close). 拥有全高根并适用 其粘稠的染色体有定向安全区域被套入.

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

<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 祖师相.

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 以备决定记录.

FzFrameTemplate

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

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

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

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

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

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

<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 例:指没有贝壳祖先拥有卷轴容器.

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 以备决定记录.

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

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

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

它的合约是JSON Schema 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 §10作为理由——这是项目困难的制约因素,而不是偏好.