Naive UI Layout 布局组件完全指南从基础骨架到 Sider 折叠与定位实战【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址: https://gitcode.com/gh_mirrors/na/naive-uiNaive UI 的Layout是一套由n-layout、n-layout-header、n-layout-sider、n-layout-content、n-layout-footer五个子组件组成的页面骨架体系用于快速搭建后台管理系统的整体结构。本文以 Layout 官方文档 为核心完整覆盖其全部 API 参数、11 个官方示例并结合 Layout.tsx 与 LayoutSider.tsx 的源码实现讲解组件组合方式、Sider 折叠的两种模式、绝对定位布局、内置滚动条以及 v2.3.0 之后的has-sider行为变更。读完本文你将能够根据实际业务场景独立搭建可折叠侧边栏、固定头部底部、独立滚动区域等完整页面布局。Layout 组件家族与基本页面骨架Layout 是一个专为布局而生的复合组件官方文档将其类比为手动挡汽车——组件本身不复杂但每个子组件承担明确职责组合起来才能发挥威力。它由五个独立组件构成组件职责n-layout布局容器可内嵌 header / sider / content / footern-layout-header顶部区域n-layout-sider侧边栏区域n-layout-content内容区域负责承载页面主体与滚动n-layout-footer底部区域最小可用的骨架如下取自 basic.demo.vuetemplate n-space vertical sizelarge !-- 上下结构header content footer -- n-layout n-layout-headerYiheyuan Road/n-layout-header n-layout-content content-stylepadding: 24px; Pingshan Road /n-layout-content n-layout-footerChengfu Road/n-layout-footer /n-layout !-- 左右结构sider content -- n-layout has-sider n-layout-sider content-stylepadding: 24px; Handian Bridge /n-layout-sider n-layout-content content-stylepadding: 24px; Pingshan Road /n-layout-content /n-layout !-- 完整结构sider (header content footer) -- n-layout has-sider n-layout-sider content-stylepadding: 24px; Handian Bridge /n-layout-sider n-layout n-layout-headerYiheyuan Road/n-layout-header n-layout-content content-stylepadding: 24px; Pingshan Road /n-layout-content n-layout-footerChengfu Road/n-layout-footer /n-layout /n-layout /n-space /template style .n-layout-header, .n-layout-footer { background: rgba(128, 128, 128, 0.2); padding: 24px; } .n-layout-sider { background: rgba(128, 128, 128, 0.3); } .n-layout-content { background: rgba(128, 128, 128, 0.4); } /style注意n-layout既可作最外层容器也可嵌套在n-layout-sider旁边作为右半部分容器。示例中的n-layout has-sider表示此容器内部含有 sider这是 v2.3.0 之后必须显式声明的关键属性详见下文。v2.3.0 之后的行为变更为什么必须声明 has-sider文档的Changes After v2.3.0章节是使用 Sider 前必读的兼容性说明。出于性能和 SSR 的考虑v2.3.0 之后凡是在n-layout内放置了n-layout-sider就必须在该n-layout上显式设置has-sider否则折叠功能不会正常工作同时positionabsolute的n-layout-sider不支持折叠。!-- v2.3.0 之前已废弃 -- n-layout n-layout-sider / n-layout / /n-layout !-- v2.3.0 之后 -- n-layout has-sider n-layout-sider / n-layout / /n-layout从源码可以印证这一约束hasSider是 Layout.tsx 中layoutProps的声明项之一当它为true时布局容器会切换为display: flex; flex-direction: row; flex-wrap: nowrap; width: 100%的横向弹性布局见 Layout.tsx使 sider 与 content 并排排列。同时n-layout-sider在开发环境下会做两类警告校验见 LayoutSider.tsxsider 被放在n-layout之外时警告Layout sider is not allowed to be put outside layout.sider 所在的n-layout未设置has-sider时警告You are putting n-layout-sider in a n-layout but havent set has-sider on the n-layout.。这两条warn提示能帮助你在开发阶段尽早发现布局声明错误。Sider 折叠collapse-mode 两种模式与内置触发器Sider 折叠是后台布局最常用的交互。官方提供了两个相关示例collapse.demo.vue左侧 Sider 折叠与 collapse-right.demo.vue右侧 Sider 折叠核心属性如下属性类型默认值说明collapse-modetransform \| widthtransformwidth模式下 Sider 内容宽度被真实折叠transform模式下 Sider 仅平移位置不改变内容宽度collapsedbooleanundefined受控折叠状态仅当position为static时生效default-collapsedbooleanfalse非受控模式下的默认折叠状态collapsed-widthnumber48折叠后的宽度widthnumber \| string272展开宽度数字时自动追加 pxshow-triggerboolean \| bar \| arrow-circlefalse是否显示内置触发按钮可选条形bar或圆形箭头arrow-circleon-update:collapsed(collapsed: boolean) voidundefined折叠状态变化回调on-after-enter/on-after-leave() voidundefined展开/折叠动画结束回调左侧 Sider 折叠的标准写法n-layout has-sider n-layout-sider collapse-modewidth :collapsed-width120 :width240 show-triggerbar content-stylepadding: 24px; bordered pHandian Bridge .../p /n-layout-sider n-layout-content content-stylepadding: 24px; Pingshan Road /n-layout-content /n-layout右侧 Sidersider-placementright写法n-layout has-sider sider-placementright n-layout-content content-stylepadding: 24px; Pingshan Road /n-layout-content n-layout-sider collapse-modewidth :collapsed-width120 :width240 show-triggerarrow-circle content-stylepadding: 24px; bordered pHandian Bridge .../p /n-layout-sider /n-layout两种折叠模式的本质区别从源码看collapse-mode决定折叠时的 DOM 处理方式见 LayoutSider.tsxwidth模式通过max-width属性在展开宽度props.width与折叠宽度props.collapsedWidth之间切换源码使用formatLength将数字格式化为带 px 的 CSS 长度内容宽度随折叠真实收缩适合需要把空间让给内容区的场景transform模式容器外层保持minWidth: formatLength(props.width)不变仅让整个 Sider 平移内容宽度不被压缩适合折叠后内容如图标菜单仍需要完整宽度展示的场景。两种模式下均可配合show-triggerbar竖条触发器或show-triggerarrow-circle圆形箭头触发器使用。折叠动画结束后会通过监听transitionende.propertyName max-width触发onAfterEnter/onAfterLeave见 LayoutSider.tsx。受控与非受控折叠collapsed是受控属性与default-collapsed非受控配合使用。源码中使用useMergedState将受控值与内部uncontrolledCollapsedRef合并见 LayoutSider.tsx。点击触发器时handleTriggerClick会依次调用onUpdate:collapsed、onUpdateCollapsed并更新内部非受控状态同时保留对旧版onExpand/onCollapse事件的兼容调用见 LayoutSider.tsx。script langts setup import { ref } from vue const collapsed ref(false) /script template n-layout has-sider n-layout-sider :collapsedcollapsed collapse-modewidth show-triggerbar update:collapsed(v) (collapsed v) !-- sider 内容 -- /n-layout-sider n-layout-content.../n-layout-content /n-layout /template折叠后隐藏内容show-collapsed-content折叠后如果不想看到 Sider 内部的文字内容例如只保留图标菜单设置:show-collapsed-contentfalse即可见 show-sider-content.demo.vue该属性默认值为truen-layout-sider collapse-modewidth :collapsed-width120 :width240 :show-collapsed-contentfalse show-triggerarrow-circle content-stylepadding: 24px; bordered Handian Bridge ... /n-layout-sider绝对定位在固定区域内部滚动position属性是所有布局子组件通用的关键定位开关官方通过 absolute.demo.vue 演示了在固定高度容器内局部滚动的经典场景。取值及效果static默认CSSposition: static按文档流正常排列absoluteCSSposition: absolute且left/right/top/bottom自动设为0组件铺满最近的相对定位祖先容器。这个模式非常适合让内容在固定容器内滚动、或让整页布局固定定位。典型用法——外层固定高度 360pxheader/footer 固定各 64px中间区域绝对定位并自行滚动div styleheight: 360px; position: relative n-layout positionabsolute n-layout-header styleheight: 64px; padding: 24px bordered Yiheyuan Road /n-layout-header n-layout has-sider positionabsolute styletop: 64px; bottom: 64px n-layout-sider bordered content-stylepadding: 24px; Handian Bridge /n-layout-sider n-layout content-stylepadding: 24px; !-- 多个 n-h2 内容超出区域滚动 -- /n-layout /n-layout n-layout-footer bordered positionabsolute styleheight: 64px; padding: 24px Chengfu Road /n-layout-footer /n-layout /div注意各子组件positionabsolute时四条边定位的差异由文档 API 明确n-layout/n-layout-contentleft, right, top, bottom均置 0n-layout-headerleft, right, bottom置 0顶部贴紧容器上缘可通过height控制n-layout-footerleft, right, top置 0底部贴紧容器下缘n-layout-siderleft, top, bottom置 0左侧贴紧高度撑满。因此 absolute.demo 中通过styletop: 64px; bottom: 64px手动收窄中间区域的上下边界实现头部在上、底部在下、中间独立滚动的效果。绝对定位布局需要你自行调整组件样式以达到预期这是官方文档明确提醒的使用前提。滚动条策略原生滚动条与内置滚动条native-scrollbar是 Layout / Layout Content / Layout Sider 共有的滚动控制属性true默认使用浏览器原生滚动条false使用 Naive UI 自带的仿制滚动条内部渲染NScrollbar。当原生滚动条与 Naive UI 视觉风格不协调时建议关闭原生滚动条。完整示例见 scrollbar.demo.vuen-layout styleheight: 360px n-layout-header styleheight: 64px; padding: 24px bordered Yiheyuan Road /n-layout-header n-layout positionabsolute styletop: 64px; bottom: 64px has-sider n-layout-sider content-stylepadding: 24px; :native-scrollbarfalse bordered !-- 大量 n-h2 内容 -- /n-layout-sider n-layout content-stylepadding: 24px; :native-scrollbarfalse !-- 大量 n-h2 内容 -- /n-layout /n-layout n-layout-footer positionabsolute styleheight: 64px; padding: 24px bordered Chengfu Road /n-layout-footer /n-layout从源码可以确认滚动行为会根据该属性分流见 Layout.tsx使用原生滚动条时scrollTo直接调用 DOM 元素的scrollTo关闭原生滚动条后则委托给内部scrollbarInstRef.scrollTo且两种模式下都会通过useReactivated在组件重新激活时恢复scrollTop/scrollLeft见 Layout.tsx。scrollbar-props属性可将 Scrollbar 组件的全部属性透传给内置滚动条用于进一步定制滚动条外观与行为。编程式滚动scrollTo 方法Layout、Layout Content、Layout Sider 三个组件均暴露scrollTo方法支持两种调用签名scroll-to.demo.vuescript langts setup import type { LayoutInst, LayoutSiderInst } from naive-ui import { ref } from vue const siderRef refLayoutSiderInst | null(null) const contentRef refLayoutInst | null(null) /script template n-space n-button clicksiderRef?.scrollTo({ top: 120, behavior: smooth }) Sider scroll to 120px /n-button n-button clickcontentRef?.scrollTo({ top: 120, behavior: smooth }) Content scroll to 120px /n-button /n-space n-layout styleheight: 360px n-layout-header styleheight: 64px; padding: 24px bordered.../n-layout-header n-layout has-sider positionabsolute styletop: 64px; bottom: 64px n-layout-sider refsiderRef bordered content-stylepadding: 24px;.../n-layout-sider n-layout-content refcontentRef content-stylepadding: 24px; :native-scrollbarfalse .../n-layout-content /n-layout n-layout-footer bordered positionabsolute styleheight: 64px; padding: 24px.../n-layout-footer /n-layout /template方法签名scrollTo((xCoord: number, yCoord: number) void) scrollTo(options: { left?: number, top?: number, behavior: smooth | auto }) void与native-scrollbar一致该方法在原生滚动条模式下作用于实际 DOM 元素在内置滚动条模式下委托给NScrollbar实例见 Layout.tsx 与 LayoutSider.tsx。此外滚动事件可通过on-scroll: (e: Event) void监听。视觉表现bordered、inverted 与 embeddedbordered 边框n-layout-sider、n-layout-header、n-layout-footer都支持bordered属性用于显示分隔边框border.demo.vuen-layout has-sider n-layout-sider bordered content-stylepadding: 24px; Handian Bridge /n-layout-sider n-layout n-layout-header borderedYiheyuan Road/n-layout-header n-layout-content content-stylepadding: 24px;Pingshan Road/n-layout-content n-layout-footer borderedChengfu Road/n-layout-footer /n-layout /n-layoutinverted 反色inverted可在 header、footer、sider 上设置用于提供高对比度的深色背景通常与n-menu的inverted搭配使用inverted.demo.vuen-layout n-layout-header :invertedinverted bordered n-menu modehorizontal :invertedinverted :optionsmenuOptions / /n-layout-header n-layout has-sider n-layout-sider bordered show-trigger collapse-modewidth :collapsed-width64 :width240 :native-scrollbarfalse :invertedinverted stylemax-height: 320px n-menu :invertedinverted :optionsmenuOptions / /n-layout-sider n-layout stylemax-height: 320px / /n-layout n-layout-footer :invertedinverted borderedFooter Footer Footer/n-layout-footer /n-layout从源码的 CSS 变量计算可以看出inverted的底层逻辑见 LayoutSider.tsx开启反色时背景色、文字色、边框色分别切换为主题中的siderColorInverted/textColorInverted/siderBorderColorInverted并为滚动条设置__invertScrollbar以适配深色外观未开启时使用普通主题变量。embedded 嵌入效果n-layout与n-layout-content支持embedded使用更深的背景营造内容嵌入的层次感特别适合突出卡片类内容。官方说明该效果仅对浅色主题生效embedded.demo.vuen-layout embedded content-stylepadding: 24px; n-card All you need to do to look to those clouds, and every day be in a good mood. /n-card /n-layout源码中对应逻辑在 Layout.tsx--n-color: props.embedded ? self.colorEmbedded : self.color即embedded为真时使用主题中的colorEmbedded作为背景色与普通color区分。内容区域的内边距content-style 的正确打开方式官方在 set-padding.demo.vue 中给出了一条重要建议不要直接在n-layout-sider/n-layout根节点上设置 padding而应通过content-style或content-class作用到可滚动的内容节点上因为组件根节点与内部滚动容器是两个不同的 DOM 层。对比示例!-- 不推荐把 padding 设置在组件根节点 -- n-layout has-sider styleheight: 240px n-layout-sider stylepadding: 24px n-h2... Not Recommended/n-h2 !-- 多个占位内容 -- /n-layout-sider /n-layout !-- 推荐通过 content-style 作用于滚动内容节点 -- n-layout has-sider styleheight: 240px n-layout-sider content-stylepadding: 24px; n-h2Recommended/n-h2 !-- 多个占位内容 -- /n-layout-sider /n-layoutcontent-style支持string | Object两种写法content-class自 2.36.0 起可用则用于传入类名。该属性存在于 Layout、Layout Content、Layout Sider 三个组件上。理解组件 DOM 结构后再决定内边距作用位置可以避免出现内容贴着边框或滚动条位置异常等问题。完整 API 参考以下 API 全部取自 index.demo-entry.md标注的版本号与默认值均为官方文档原始声明。Layout、Layout Content PropsNameTypeDefaultDescriptionVersioncontent-classstringundefinedClass of scrollable content node.2.36.0content-stylestring \| ObjectundefinedStyle of scrollable content node.embeddedbooleanfalseUse darker background to show a embedded effect. Only work for light theme.has-siderbooleanfalseWhether the component has sider inside. If so it must betrue.native-scrollbarbooleantrueWhether to use native scrollbar on itself. If set tofalse, layout will use a naive-ui style scrollbar for content.positionstatic \| absolutestaticstaticposition will make it css position set tostatic.absoluteposition will make it css position set toabsoluteandleft,right,top,bottomto0.scrollbar-propsScrollbarPropsundefined透传给内置滚动条详见 Scrollbar props。sider-placementleft \| rightleftThe sidebar is displayed on the left or the right side.on-scroll(e: Event) voidundefinedCallback function when the content scroll.Layout Footer PropsNameTypeDefaultDescriptionborderedbooleanfalseWhether to show the border.invertedbooleanfalseWhether to use inverted background.positionstatic \| absolutestaticabsolute模式下left,right,top置 0适合固定底部。Layout Header PropsNameTypeDefaultDescriptionborderedbooleanfalseWhether to show the border.invertedbooleanfalseWhether to use inverted background.positionstatic \| absolutestaticabsolute模式下left,right,bottom置 0适合固定顶部。Layout Sider PropsNameTypeDefaultDescriptionVersionborderedbooleanfalseWhether to show the border.collapse-modetransform \| widthtransformwidth真实折叠内容宽度transform仅平移位置、不改内容宽度。collapsedbooleanundefined受控折叠状态仅对positionstatic生效。collapsed-trigger-classstringundefinedTrigger class when collapsed.2.36.0collapsed-trigger-stylestring \| ObjectundefinedTrigger style when collapsed.collapsed-widthnumber48Folded width.content-classstringundefinedClass of scrollable content node.content-stylestring \| ObjectundefinedStyle of scrollable content node.default-collapsedbooleanfalseDefault collapsed state in uncontrolled mode.invertedbooleanfalseWhether to use inverted background.native-scrollbarbooleantrue是否使用原生滚动条false时使用 Naive UI 风格滚动条。positionstatic \| absolutestaticabsolute模式下left,top,bottom置 0。scrollbar-propsScrollbarPropsundefined透传给内置滚动条详见 Scrollbar props。show-collapsed-contentbooleantrueWhether to show content in sider after it is collapsed.show-triggerboolean \| bar \| arrow-circlefalseWhether to show the built-in trigger button on sider.trigger-classstringundefinedTrigger class.2.36.0trigger-stylestring \| ObjectundefinedTrigger style.widthnumber \| string272Width CSS value. When it is number, px will be added.on-after-enter() voidundefinedCallback after its expanded.on-after-leave() voidundefinedCallback after its collapsed.on-scroll(e: Event) voidundefinedCallback function when the content scroll.on-update:collapsed(collapsed: boolean) voidundefinedCallback function when the folding state changes.SlotsLayout、Layout Content、Layout Sider、Layout Header、Layout Footer 均提供default插槽参数()用于承载布局内容NameParametersDescriptiondefault()Layout content.MethodsLayout、Layout Content、Layout Sider 均暴露scrollTo方法NameTypeDescriptionscrollTo((xCoord: number, yCoord: number) void) \| (options: { left?: number, top?: number, behavior: smooth \| auto }) voidScroll to somewhere.源码中的默认值印证与扩展阅读上文引用的所有默认值均可直接在源码中找到定义n-layout的nativeScrollbar默认true、siderPlacement默认left、hasSider默认falseLayout.tsxn-layout-sider的collapsedWidth默认48、width默认272、collapseMode默认transform、showTrigger默认false、showCollapsedContent默认trueLayoutSider.tsx。若需要深度定制主题变量如colorEmbedded、siderColorInverted、siderToggleButtonColor等可参考 layout 的 light/dark 主题定义 与 样式文件。组件的类型定义LayoutInst、LayoutSiderInst位于 interface.ts单元测试与 SSR 测试可参见 Layout.spec.ts 与 server.spec.tsx。所有示例的完整源码都存放在 src/layout/demos/enUS 目录下可直接复制到项目中运行验证。小结Naive UI 的 Layout 组件以五个子组件为骨架通过has-sider、position、native-scrollbar、collapse-mode、inverted、embedded等核心属性组合出几乎全部的后台页面结构。实战中记住三条主线即可v2.3.0 之后凡含 Sider 必须声明has-sider固定区域滚动用positionabsolute 手动边界样式内边距统一走content-style而不是组件根节点。配合show-trigger内置触发器、scrollTo方法以及content-class/content-style2.36.0对滚动内容节点的精细控制Layout 足以胜任从简单单页到复杂管理后台的各种布局需求。【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址: https://gitcode.com/gh_mirrors/na/naive-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Naive UI Layout 布局组件完全指南从基础骨架到 Sider 折叠与定位实战【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址: https://gitcode.com/gh_mirrors/na/naive-uiNaive UI 的Layout是一套由n-layout、n-layout-header、n-layout-sider、n-layout-content、n-layout-footer五个子组件组成的页面骨架体系用于快速搭建后台管理系统的整体结构。本文以 Layout 官方文档 为核心完整覆盖其全部 API 参数、11 个官方示例并结合 Layout.tsx 与 LayoutSider.tsx 的源码实现讲解组件组合方式、Sider 折叠的两种模式、绝对定位布局、内置滚动条以及 v2.3.0 之后的has-sider行为变更。读完本文你将能够根据实际业务场景独立搭建可折叠侧边栏、固定头部底部、独立滚动区域等完整页面布局。Layout 组件家族与基本页面骨架Layout 是一个专为布局而生的复合组件官方文档将其类比为手动挡汽车——组件本身不复杂但每个子组件承担明确职责组合起来才能发挥威力。它由五个独立组件构成组件职责n-layout布局容器可内嵌 header / sider / content / footern-layout-header顶部区域n-layout-sider侧边栏区域n-layout-content内容区域负责承载页面主体与滚动n-layout-footer底部区域最小可用的骨架如下取自 basic.demo.vuetemplate n-space vertical sizelarge !-- 上下结构header content footer -- n-layout n-layout-headerYiheyuan Road/n-layout-header n-layout-content content-stylepadding: 24px; Pingshan Road /n-layout-content n-layout-footerChengfu Road/n-layout-footer /n-layout !-- 左右结构sider content -- n-layout has-sider n-layout-sider content-stylepadding: 24px; Handian Bridge /n-layout-sider n-layout-content content-stylepadding: 24px; Pingshan Road /n-layout-content /n-layout !-- 完整结构sider (header content footer) -- n-layout has-sider n-layout-sider content-stylepadding: 24px; Handian Bridge /n-layout-sider n-layout n-layout-headerYiheyuan Road/n-layout-header n-layout-content content-stylepadding: 24px; Pingshan Road /n-layout-content n-layout-footerChengfu Road/n-layout-footer /n-layout /n-layout /n-space /template style .n-layout-header, .n-layout-footer { background: rgba(128, 128, 128, 0.2); padding: 24px; } .n-layout-sider { background: rgba(128, 128, 128, 0.3); } .n-layout-content { background: rgba(128, 128, 128, 0.4); } /style注意n-layout既可作最外层容器也可嵌套在n-layout-sider旁边作为右半部分容器。示例中的n-layout has-sider表示此容器内部含有 sider这是 v2.3.0 之后必须显式声明的关键属性详见下文。v2.3.0 之后的行为变更为什么必须声明 has-sider文档的Changes After v2.3.0章节是使用 Sider 前必读的兼容性说明。出于性能和 SSR 的考虑v2.3.0 之后凡是在n-layout内放置了n-layout-sider就必须在该n-layout上显式设置has-sider否则折叠功能不会正常工作同时positionabsolute的n-layout-sider不支持折叠。!-- v2.3.0 之前已废弃 -- n-layout n-layout-sider / n-layout / /n-layout !-- v2.3.0 之后 -- n-layout has-sider n-layout-sider / n-layout / /n-layout从源码可以印证这一约束hasSider是 Layout.tsx 中layoutProps的声明项之一当它为true时布局容器会切换为display: flex; flex-direction: row; flex-wrap: nowrap; width: 100%的横向弹性布局见 Layout.tsx使 sider 与 content 并排排列。同时n-layout-sider在开发环境下会做两类警告校验见 LayoutSider.tsxsider 被放在n-layout之外时警告Layout sider is not allowed to be put outside layout.sider 所在的n-layout未设置has-sider时警告You are putting n-layout-sider in a n-layout but havent set has-sider on the n-layout.。这两条warn提示能帮助你在开发阶段尽早发现布局声明错误。Sider 折叠collapse-mode 两种模式与内置触发器Sider 折叠是后台布局最常用的交互。官方提供了两个相关示例collapse.demo.vue左侧 Sider 折叠与 collapse-right.demo.vue右侧 Sider 折叠核心属性如下属性类型默认值说明collapse-modetransform \| widthtransformwidth模式下 Sider 内容宽度被真实折叠transform模式下 Sider 仅平移位置不改变内容宽度collapsedbooleanundefined受控折叠状态仅当position为static时生效default-collapsedbooleanfalse非受控模式下的默认折叠状态collapsed-widthnumber48折叠后的宽度widthnumber \| string272展开宽度数字时自动追加 pxshow-triggerboolean \| bar \| arrow-circlefalse是否显示内置触发按钮可选条形bar或圆形箭头arrow-circleon-update:collapsed(collapsed: boolean) voidundefined折叠状态变化回调on-after-enter/on-after-leave() voidundefined展开/折叠动画结束回调左侧 Sider 折叠的标准写法n-layout has-sider n-layout-sider collapse-modewidth :collapsed-width120 :width240 show-triggerbar content-stylepadding: 24px; bordered pHandian Bridge .../p /n-layout-sider n-layout-content content-stylepadding: 24px; Pingshan Road /n-layout-content /n-layout右侧 Sidersider-placementright写法n-layout has-sider sider-placementright n-layout-content content-stylepadding: 24px; Pingshan Road /n-layout-content n-layout-sider collapse-modewidth :collapsed-width120 :width240 show-triggerarrow-circle content-stylepadding: 24px; bordered pHandian Bridge .../p /n-layout-sider /n-layout两种折叠模式的本质区别从源码看collapse-mode决定折叠时的 DOM 处理方式见 LayoutSider.tsxwidth模式通过max-width属性在展开宽度props.width与折叠宽度props.collapsedWidth之间切换源码使用formatLength将数字格式化为带 px 的 CSS 长度内容宽度随折叠真实收缩适合需要把空间让给内容区的场景transform模式容器外层保持minWidth: formatLength(props.width)不变仅让整个 Sider 平移内容宽度不被压缩适合折叠后内容如图标菜单仍需要完整宽度展示的场景。两种模式下均可配合show-triggerbar竖条触发器或show-triggerarrow-circle圆形箭头触发器使用。折叠动画结束后会通过监听transitionende.propertyName max-width触发onAfterEnter/onAfterLeave见 LayoutSider.tsx。受控与非受控折叠collapsed是受控属性与default-collapsed非受控配合使用。源码中使用useMergedState将受控值与内部uncontrolledCollapsedRef合并见 LayoutSider.tsx。点击触发器时handleTriggerClick会依次调用onUpdate:collapsed、onUpdateCollapsed并更新内部非受控状态同时保留对旧版onExpand/onCollapse事件的兼容调用见 LayoutSider.tsx。script langts setup import { ref } from vue const collapsed ref(false) /script template n-layout has-sider n-layout-sider :collapsedcollapsed collapse-modewidth show-triggerbar update:collapsed(v) (collapsed v) !-- sider 内容 -- /n-layout-sider n-layout-content.../n-layout-content /n-layout /template折叠后隐藏内容show-collapsed-content折叠后如果不想看到 Sider 内部的文字内容例如只保留图标菜单设置:show-collapsed-contentfalse即可见 show-sider-content.demo.vue该属性默认值为truen-layout-sider collapse-modewidth :collapsed-width120 :width240 :show-collapsed-contentfalse show-triggerarrow-circle content-stylepadding: 24px; bordered Handian Bridge ... /n-layout-sider绝对定位在固定区域内部滚动position属性是所有布局子组件通用的关键定位开关官方通过 absolute.demo.vue 演示了在固定高度容器内局部滚动的经典场景。取值及效果static默认CSSposition: static按文档流正常排列absoluteCSSposition: absolute且left/right/top/bottom自动设为0组件铺满最近的相对定位祖先容器。这个模式非常适合让内容在固定容器内滚动、或让整页布局固定定位。典型用法——外层固定高度 360pxheader/footer 固定各 64px中间区域绝对定位并自行滚动div styleheight: 360px; position: relative n-layout positionabsolute n-layout-header styleheight: 64px; padding: 24px bordered Yiheyuan Road /n-layout-header n-layout has-sider positionabsolute styletop: 64px; bottom: 64px n-layout-sider bordered content-stylepadding: 24px; Handian Bridge /n-layout-sider n-layout content-stylepadding: 24px; !-- 多个 n-h2 内容超出区域滚动 -- /n-layout /n-layout n-layout-footer bordered positionabsolute styleheight: 64px; padding: 24px Chengfu Road /n-layout-footer /n-layout /div注意各子组件positionabsolute时四条边定位的差异由文档 API 明确n-layout/n-layout-contentleft, right, top, bottom均置 0n-layout-headerleft, right, bottom置 0顶部贴紧容器上缘可通过height控制n-layout-footerleft, right, top置 0底部贴紧容器下缘n-layout-siderleft, top, bottom置 0左侧贴紧高度撑满。因此 absolute.demo 中通过styletop: 64px; bottom: 64px手动收窄中间区域的上下边界实现头部在上、底部在下、中间独立滚动的效果。绝对定位布局需要你自行调整组件样式以达到预期这是官方文档明确提醒的使用前提。滚动条策略原生滚动条与内置滚动条native-scrollbar是 Layout / Layout Content / Layout Sider 共有的滚动控制属性true默认使用浏览器原生滚动条false使用 Naive UI 自带的仿制滚动条内部渲染NScrollbar。当原生滚动条与 Naive UI 视觉风格不协调时建议关闭原生滚动条。完整示例见 scrollbar.demo.vuen-layout styleheight: 360px n-layout-header styleheight: 64px; padding: 24px bordered Yiheyuan Road /n-layout-header n-layout positionabsolute styletop: 64px; bottom: 64px has-sider n-layout-sider content-stylepadding: 24px; :native-scrollbarfalse bordered !-- 大量 n-h2 内容 -- /n-layout-sider n-layout content-stylepadding: 24px; :native-scrollbarfalse !-- 大量 n-h2 内容 -- /n-layout /n-layout n-layout-footer positionabsolute styleheight: 64px; padding: 24px bordered Chengfu Road /n-layout-footer /n-layout从源码可以确认滚动行为会根据该属性分流见 Layout.tsx使用原生滚动条时scrollTo直接调用 DOM 元素的scrollTo关闭原生滚动条后则委托给内部scrollbarInstRef.scrollTo且两种模式下都会通过useReactivated在组件重新激活时恢复scrollTop/scrollLeft见 Layout.tsx。scrollbar-props属性可将 Scrollbar 组件的全部属性透传给内置滚动条用于进一步定制滚动条外观与行为。编程式滚动scrollTo 方法Layout、Layout Content、Layout Sider 三个组件均暴露scrollTo方法支持两种调用签名scroll-to.demo.vuescript langts setup import type { LayoutInst, LayoutSiderInst } from naive-ui import { ref } from vue const siderRef refLayoutSiderInst | null(null) const contentRef refLayoutInst | null(null) /script template n-space n-button clicksiderRef?.scrollTo({ top: 120, behavior: smooth }) Sider scroll to 120px /n-button n-button clickcontentRef?.scrollTo({ top: 120, behavior: smooth }) Content scroll to 120px /n-button /n-space n-layout styleheight: 360px n-layout-header styleheight: 64px; padding: 24px bordered.../n-layout-header n-layout has-sider positionabsolute styletop: 64px; bottom: 64px n-layout-sider refsiderRef bordered content-stylepadding: 24px;.../n-layout-sider n-layout-content refcontentRef content-stylepadding: 24px; :native-scrollbarfalse .../n-layout-content /n-layout n-layout-footer bordered positionabsolute styleheight: 64px; padding: 24px.../n-layout-footer /n-layout /template方法签名scrollTo((xCoord: number, yCoord: number) void) scrollTo(options: { left?: number, top?: number, behavior: smooth | auto }) void与native-scrollbar一致该方法在原生滚动条模式下作用于实际 DOM 元素在内置滚动条模式下委托给NScrollbar实例见 Layout.tsx 与 LayoutSider.tsx。此外滚动事件可通过on-scroll: (e: Event) void监听。视觉表现bordered、inverted 与 embeddedbordered 边框n-layout-sider、n-layout-header、n-layout-footer都支持bordered属性用于显示分隔边框border.demo.vuen-layout has-sider n-layout-sider bordered content-stylepadding: 24px; Handian Bridge /n-layout-sider n-layout n-layout-header borderedYiheyuan Road/n-layout-header n-layout-content content-stylepadding: 24px;Pingshan Road/n-layout-content n-layout-footer borderedChengfu Road/n-layout-footer /n-layout /n-layoutinverted 反色inverted可在 header、footer、sider 上设置用于提供高对比度的深色背景通常与n-menu的inverted搭配使用inverted.demo.vuen-layout n-layout-header :invertedinverted bordered n-menu modehorizontal :invertedinverted :optionsmenuOptions / /n-layout-header n-layout has-sider n-layout-sider bordered show-trigger collapse-modewidth :collapsed-width64 :width240 :native-scrollbarfalse :invertedinverted stylemax-height: 320px n-menu :invertedinverted :optionsmenuOptions / /n-layout-sider n-layout stylemax-height: 320px / /n-layout n-layout-footer :invertedinverted borderedFooter Footer Footer/n-layout-footer /n-layout从源码的 CSS 变量计算可以看出inverted的底层逻辑见 LayoutSider.tsx开启反色时背景色、文字色、边框色分别切换为主题中的siderColorInverted/textColorInverted/siderBorderColorInverted并为滚动条设置__invertScrollbar以适配深色外观未开启时使用普通主题变量。embedded 嵌入效果n-layout与n-layout-content支持embedded使用更深的背景营造内容嵌入的层次感特别适合突出卡片类内容。官方说明该效果仅对浅色主题生效embedded.demo.vuen-layout embedded content-stylepadding: 24px; n-card All you need to do to look to those clouds, and every day be in a good mood. /n-card /n-layout源码中对应逻辑在 Layout.tsx--n-color: props.embedded ? self.colorEmbedded : self.color即embedded为真时使用主题中的colorEmbedded作为背景色与普通color区分。内容区域的内边距content-style 的正确打开方式官方在 set-padding.demo.vue 中给出了一条重要建议不要直接在n-layout-sider/n-layout根节点上设置 padding而应通过content-style或content-class作用到可滚动的内容节点上因为组件根节点与内部滚动容器是两个不同的 DOM 层。对比示例!-- 不推荐把 padding 设置在组件根节点 -- n-layout has-sider styleheight: 240px n-layout-sider stylepadding: 24px n-h2... Not Recommended/n-h2 !-- 多个占位内容 -- /n-layout-sider /n-layout !-- 推荐通过 content-style 作用于滚动内容节点 -- n-layout has-sider styleheight: 240px n-layout-sider content-stylepadding: 24px; n-h2Recommended/n-h2 !-- 多个占位内容 -- /n-layout-sider /n-layoutcontent-style支持string | Object两种写法content-class自 2.36.0 起可用则用于传入类名。该属性存在于 Layout、Layout Content、Layout Sider 三个组件上。理解组件 DOM 结构后再决定内边距作用位置可以避免出现内容贴着边框或滚动条位置异常等问题。完整 API 参考以下 API 全部取自 index.demo-entry.md标注的版本号与默认值均为官方文档原始声明。Layout、Layout Content PropsNameTypeDefaultDescriptionVersioncontent-classstringundefinedClass of scrollable content node.2.36.0content-stylestring \| ObjectundefinedStyle of scrollable content node.embeddedbooleanfalseUse darker background to show a embedded effect. Only work for light theme.has-siderbooleanfalseWhether the component has sider inside. If so it must betrue.native-scrollbarbooleantrueWhether to use native scrollbar on itself. If set tofalse, layout will use a naive-ui style scrollbar for content.positionstatic \| absolutestaticstaticposition will make it css position set tostatic.absoluteposition will make it css position set toabsoluteandleft,right,top,bottomto0.scrollbar-propsScrollbarPropsundefined透传给内置滚动条详见 Scrollbar props。sider-placementleft \| rightleftThe sidebar is displayed on the left or the right side.on-scroll(e: Event) voidundefinedCallback function when the content scroll.Layout Footer PropsNameTypeDefaultDescriptionborderedbooleanfalseWhether to show the border.invertedbooleanfalseWhether to use inverted background.positionstatic \| absolutestaticabsolute模式下left,right,top置 0适合固定底部。Layout Header PropsNameTypeDefaultDescriptionborderedbooleanfalseWhether to show the border.invertedbooleanfalseWhether to use inverted background.positionstatic \| absolutestaticabsolute模式下left,right,bottom置 0适合固定顶部。Layout Sider PropsNameTypeDefaultDescriptionVersionborderedbooleanfalseWhether to show the border.collapse-modetransform \| widthtransformwidth真实折叠内容宽度transform仅平移位置、不改内容宽度。collapsedbooleanundefined受控折叠状态仅对positionstatic生效。collapsed-trigger-classstringundefinedTrigger class when collapsed.2.36.0collapsed-trigger-stylestring \| ObjectundefinedTrigger style when collapsed.collapsed-widthnumber48Folded width.content-classstringundefinedClass of scrollable content node.content-stylestring \| ObjectundefinedStyle of scrollable content node.default-collapsedbooleanfalseDefault collapsed state in uncontrolled mode.invertedbooleanfalseWhether to use inverted background.native-scrollbarbooleantrue是否使用原生滚动条false时使用 Naive UI 风格滚动条。positionstatic \| absolutestaticabsolute模式下left,top,bottom置 0。scrollbar-propsScrollbarPropsundefined透传给内置滚动条详见 Scrollbar props。show-collapsed-contentbooleantrueWhether to show content in sider after it is collapsed.show-triggerboolean \| bar \| arrow-circlefalseWhether to show the built-in trigger button on sider.trigger-classstringundefinedTrigger class.2.36.0trigger-stylestring \| ObjectundefinedTrigger style.widthnumber \| string272Width CSS value. When it is number, px will be added.on-after-enter() voidundefinedCallback after its expanded.on-after-leave() voidundefinedCallback after its collapsed.on-scroll(e: Event) voidundefinedCallback function when the content scroll.on-update:collapsed(collapsed: boolean) voidundefinedCallback function when the folding state changes.SlotsLayout、Layout Content、Layout Sider、Layout Header、Layout Footer 均提供default插槽参数()用于承载布局内容NameParametersDescriptiondefault()Layout content.MethodsLayout、Layout Content、Layout Sider 均暴露scrollTo方法NameTypeDescriptionscrollTo((xCoord: number, yCoord: number) void) \| (options: { left?: number, top?: number, behavior: smooth \| auto }) voidScroll to somewhere.源码中的默认值印证与扩展阅读上文引用的所有默认值均可直接在源码中找到定义n-layout的nativeScrollbar默认true、siderPlacement默认left、hasSider默认falseLayout.tsxn-layout-sider的collapsedWidth默认48、width默认272、collapseMode默认transform、showTrigger默认false、showCollapsedContent默认trueLayoutSider.tsx。若需要深度定制主题变量如colorEmbedded、siderColorInverted、siderToggleButtonColor等可参考 layout 的 light/dark 主题定义 与 样式文件。组件的类型定义LayoutInst、LayoutSiderInst位于 interface.ts单元测试与 SSR 测试可参见 Layout.spec.ts 与 server.spec.tsx。所有示例的完整源码都存放在 src/layout/demos/enUS 目录下可直接复制到项目中运行验证。小结Naive UI 的 Layout 组件以五个子组件为骨架通过has-sider、position、native-scrollbar、collapse-mode、inverted、embedded等核心属性组合出几乎全部的后台页面结构。实战中记住三条主线即可v2.3.0 之后凡含 Sider 必须声明has-sider固定区域滚动用positionabsolute 手动边界样式内边距统一走content-style而不是组件根节点。配合show-trigger内置触发器、scrollTo方法以及content-class/content-style2.36.0对滚动内容节点的精细控制Layout 足以胜任从简单单页到复杂管理后台的各种布局需求。【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址: https://gitcode.com/gh_mirrors/na/naive-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
