Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Layout 布局
搭页面整体框架用的容器:NsLayout 是外框,里面放顶栏 NsHeader、侧边栏 NsSider、内容区 NsContent、底栏 NsFooter。侧边栏可以折叠。
引入
import { NsLayout, NsHeader, NsSider, NsContent, NsFooter } from '@ns/ui'
基础用法
上中下三段:顶栏和底栏高度固定,内容区占满剩下的高度。NsLayout 要有确定的高度,内容区才知道剩下多少。
<script setup lang="ts">
import { NsLayout, NsHeader, NsContent, NsFooter } from '@ns/ui'
</script>
<template>
<NsLayout style="height: 360px">
<NsHeader>顶栏</NsHeader>
<NsContent>内容区</NsContent>
<NsFooter>底栏</NsFooter>
</NsLayout>
</template>
带侧边栏
NsLayout 里放了 NsSider 时,不用写 direction,自动横着排:侧边栏和内容区左右并列,侧边栏的高度和 NsLayout 一样。
<template>
<NsLayout style="height: 360px">
<NsSider>侧边栏</NsSider>
<NsContent>内容区</NsContent>
</NsLayout>
</template>
顶栏加侧边栏
NsLayout 可以嵌套。外层竖着排顶栏和内层 NsLayout,内层放侧边栏和内容区,自动横排。
<template>
<NsLayout style="height: 400px">
<NsHeader>顶栏</NsHeader>
<NsLayout>
<NsSider>侧边栏</NsSider>
<NsLayout>
<NsContent>内容区</NsContent>
<NsFooter>底栏</NsFooter>
</NsLayout>
</NsLayout>
</NsLayout>
</template>
最里面那个 NsLayout 没有 NsSider,所以还是竖着排内容区和底栏。
顶栏也可以放在内容区那一侧,侧边栏从上到下占满整个高度:
<template>
<NsLayout style="height: 400px">
<NsSider>侧边栏</NsSider>
<NsLayout>
<NsHeader>顶栏</NsHeader>
<NsContent>内容区</NsContent>
<NsFooter>底栏</NsFooter>
</NsLayout>
</NsLayout>
</template>
排列方向
direction 可选 horizontal(横排)、vertical(竖排)。不写时按里面有没有 NsSider 自动决定;写了就以写的为准。下面四个布局分别是:
<template>
<div class="layouts">
<div>
<p class="label">不写,没有 NsSider:竖排</p>
<NsLayout class="box">
<NsHeader :height="40">顶栏</NsHeader>
<NsContent>内容区</NsContent>
</NsLayout>
</div>
<div>
<p class="label">不写,有 NsSider:横排</p>
<NsLayout class="box">
<NsSider :width="100">侧边栏</NsSider>
<NsContent>内容区</NsContent>
</NsLayout>
</div>
<div>
<p class="label">direction="horizontal":没有 NsSider 也横排</p>
<NsLayout direction="horizontal" class="box">
<NsContent>内容区一</NsContent>
<NsContent class="divided">内容区二</NsContent>
</NsLayout>
</div>
<div>
<p class="label">direction="vertical"</p>
<NsLayout direction="vertical" class="box">
<NsContent>内容区</NsContent>
<NsFooter :height="40">底栏</NsFooter>
</NsLayout>
</div>
</div>
</template>
<style scoped>
.layouts {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
gap: var(--ns-spacing-4);
}
.label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.box {
height: 160px;
border: 1px solid var(--ns-border-color-light);
}
.divided {
border-left: 1px solid var(--ns-border-color-light);
}
</style>
可折叠侧边栏
collapsible 在侧边栏底部加一个折叠触发条,点了在 width 和 collapsedWidth 之间切换。用 v-model:collapsed 绑定折叠状态,在外面也能控制折叠。
<script setup lang="ts">
import { ref } from 'vue'
import { NsLayout, NsHeader, NsSider, NsContent, NsButton } from '@ns/ui'
const collapsed = ref(false)
</script>
<template>
<NsLayout style="height: 400px">
<NsSider v-model:collapsed="collapsed" collapsible :width="220" :collapsed-width="64">
<span v-if="!collapsed">菜单</span>
</NsSider>
<NsLayout>
<NsHeader>
<NsButton @click="collapsed = !collapsed">{{ collapsed ? '展开' : '收起' }}</NsButton>
</NsHeader>
<NsContent>内容区</NsContent>
</NsLayout>
</NsLayout>
</template>
不绑定 collapsed 也能折叠,状态由组件自己记着。侧边栏的内容区可以滚动,触发条固定在最下面,不会盖住内容。
<template>
<NsLayout style="height: 300px">
<NsSider collapsible :width="160">
<p v-for="i in 20" :key="i" style="margin: 0; padding: 8px 16px">第 {{ i }} 项</p>
</NsSider>
<NsContent>侧边栏里有 20 项,超出的部分在侧边栏里滚动,触发条一直在最下面。</NsContent>
</NsLayout>
</template>
折叠后的宽度
width 是展开时的宽度,collapsed-width 是折叠后的宽度,都可以是数字(px)或任意 CSS 长度,默认 200 和 64。下面三个侧边栏都可以点底部的触发条折叠:
<template>
<NsSpace direction="vertical" fill>
<NsLayout style="height: 120px">
<NsSider collapsible>默认 200 / 64</NsSider>
<NsContent>width 200,collapsed-width 64</NsContent>
</NsLayout>
<NsLayout style="height: 120px">
<NsSider collapsible width="30%" collapsed-width="10%">30% / 10%</NsSider>
<NsContent>width "30%",collapsed-width "10%"</NsContent>
</NsLayout>
<NsLayout style="height: 120px">
<NsSider collapsible :width="160" :collapsed-width="120">160 / 120</NsSider>
<NsContent>width 160,collapsed-width 120</NsContent>
</NsLayout>
</NsSpace>
</template>
折叠后完全隐藏
collapsed-width 设成 0 时,折叠后侧边栏完全隐藏,触发条变成一个小按钮,浮在侧边栏外侧(距顶部 64px),点它可以再展开。
<template>
<NsLayout style="height: 360px">
<NsSider collapsible :collapsed-width="0">侧边栏</NsSider>
<NsContent>内容区</NsContent>
</NsLayout>
</template>
不显示触发条
collapsible 为 false(默认)时没有触发条,只能通过 collapsed 折叠,适合用顶栏上的按钮控制。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsContent, NsHeader, NsLayout, NsSider } from '@ns/ui'
const collapsed = ref(false)
</script>
<template>
<NsLayout style="height: 300px">
<NsHeader>
<NsButton
:icon="collapsed ? 'double-right' : 'double-left'"
:aria-label="collapsed ? '展开侧边栏' : '收起侧边栏'"
@click="collapsed = !collapsed"
/>
</NsHeader>
<NsLayout>
<NsSider :collapsed="collapsed" :width="180" :collapsed-width="0">侧边栏</NsSider>
<NsContent>点顶栏上的按钮折叠、展开侧边栏</NsContent>
</NsLayout>
</NsLayout>
</template>
右侧侧边栏
placement="right" 时侧边栏的边框在左边,触发条的箭头方向也跟着反过来。侧边栏实际显示在左边还是右边,取决于它在模板里的位置,要把它写在 NsContent 后面。
<template>
<NsLayout style="height: 360px">
<NsContent>内容区</NsContent>
<NsSider placement="right" collapsible :width="240">右侧面板</NsSider>
</NsLayout>
</template>
placement 的两个值可以同时用,内容区两侧各一个侧边栏,各自折叠:
<template>
<NsLayout style="height: 300px">
<NsSider placement="left" collapsible :width="160">左侧(left)</NsSider>
<NsContent>内容区</NsContent>
<NsSider placement="right" collapsible :width="160">右侧(right)</NsSider>
</NsLayout>
</template>
自定义触发条
trigger 插槽替换触发条里的内容,作用域参数 collapsed 是当前是否折叠。整个触发条仍是一个按钮,点击和键盘操作都由组件处理,插槽里不用再绑点击事件。
<template>
<NsLayout style="height: 360px">
<NsSider collapsible>
侧边栏
<template #trigger="{ collapsed }">
{{ collapsed ? '展开' : '收起' }}
</template>
</NsSider>
<NsContent>内容区</NsContent>
</NsLayout>
</template>
配合菜单
侧边栏里放 NsMenu,把折叠状态同时传给菜单的 collapse,折叠后菜单只显示图标。collapse 事件在点触发条切换后触发,参数是切换后是否折叠。
<script setup lang="ts">
import { ref } from 'vue'
import { NsContent, NsHeader, NsLayout, NsMenu, NsMenuItem, NsSider, NsSubMenu } from '@ns/ui'
const collapsed = ref(false)
const log = ref('')
const handleCollapse = (value: boolean) => {
log.value = value ? '侧边栏收起了' : '侧边栏展开了'
}
</script>
<template>
<NsLayout style="height: 400px">
<NsHeader>后台管理系统</NsHeader>
<NsLayout>
<NsSider
v-model:collapsed="collapsed"
collapsible
:width="200"
:collapsed-width="64"
@collapse="handleCollapse"
>
<NsMenu :collapse="collapsed" default-active="1">
<NsMenuItem index="1" icon="home">工作台</NsMenuItem>
<NsSubMenu index="2" title="系统管理" icon="setting">
<NsMenuItem index="2-1" icon="user">用户管理</NsMenuItem>
<NsMenuItem index="2-2" icon="users">角色管理</NsMenuItem>
</NsSubMenu>
<NsMenuItem index="3" icon="bell">消息中心</NsMenuItem>
</NsMenu>
</NsSider>
<NsContent>{{ log || '点侧边栏底部的触发条试试' }}</NsContent>
</NsLayout>
</NsLayout>
</template>
自定义高度和颜色
NsHeader、NsFooter 的 height 可以是数字(px)或任意 CSS 长度。颜色通过 CSS 变量改,见下面的“CSS 变量”。
<template>
<NsLayout
style="
height: 360px;
--ns-layout-header-bg-color: var(--ns-color-primary);
--ns-layout-sider-bg-color: var(--ns-fill-color-light);
"
>
<NsHeader :height="48" style="color: var(--ns-color-white)">顶栏</NsHeader>
<NsLayout>
<NsSider :width="180">侧边栏</NsSider>
<NsContent>内容区</NsContent>
</NsLayout>
<NsFooter height="40px">底栏</NsFooter>
</NsLayout>
</template>
触发条、边框、内容区的颜色也都能改。用主题变量配色时,暗色主题下颜色也会跟着变:
<template>
<NsLayout
style="
height: 300px;
--ns-layout-header-border-color: var(--ns-color-primary);
--ns-layout-sider-bg-color: var(--ns-color-primary-bg);
--ns-layout-sider-border-color: var(--ns-color-primary-bg-hover);
--ns-layout-sider-trigger-bg-color: var(--ns-color-primary-bg-hover);
--ns-layout-sider-trigger-bg-color-hover: var(--ns-color-primary-lighter);
--ns-layout-content-bg-color: var(--ns-bg-color);
--ns-layout-footer-bg-color: var(--ns-fill-color-light);
--ns-layout-footer-border-color: var(--ns-border-color);
"
>
<NsHeader :height="48">主色下边框的顶栏</NsHeader>
<NsLayout>
<NsSider collapsible :width="160">浅蓝侧边栏</NsSider>
<NsLayout>
<NsContent>白色内容区</NsContent>
<NsFooter :height="48">浅灰底栏</NsFooter>
</NsLayout>
</NsLayout>
</NsLayout>
</template>
NsLayout Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| direction | 'horizontal' | 'vertical' | - | 子元素的排列方向。不写时,里面有 NsSider 就是 'horizontal',没有就是 'vertical' |
NsHeader Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| height | string | number | 60 | 高度。数字单位是 px,字符串原样用 |
NsFooter Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| height | string | number | 60 | 高度。数字单位是 px,字符串原样用 |
NsSider Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| width | string | number | 200 | 展开时的宽度。数字单位是 px,字符串原样用 |
| collapsedWidth | string | number | 64 | 折叠后的宽度。为 0 时折叠后完全隐藏,触发条浮在侧边栏外侧 |
| collapsed | boolean | false | 是否折叠,支持 v-model:collapsed |
| placement | 'left' | 'right' | 'left' | 侧边栏在哪一侧,决定边框和触发条箭头的方向 |
| collapsible | boolean | false | 是否显示折叠触发条。为 false 时没有触发条,只能通过 collapsed 折叠 |
NsContent 没有属性。
NsSider Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:collapsed | (value: boolean) | 用户点触发条切换折叠时触发,v-model:collapsed 用的就是它 |
| collapse | (value: boolean) | 用户点触发条切换折叠时触发,参数是切换后是否折叠 |
Slots
| 组件 | 插槽 | 作用域参数 | 说明 |
|---|---|---|---|
| NsLayout | default | - | 放 Header、Sider、Content 等 |
| NsHeader | default | - | 顶栏的内容 |
| NsSider | default | - | 侧边栏的内容 |
| NsSider | trigger | { collapsed: boolean } | 折叠触发条里的内容 |
| NsContent | default | - | 内容区的内容 |
| NsFooter | default | - | 底栏的内容 |
类型
import type { LayoutProps, HeaderProps, FooterProps, SiderProps, ContentProps } from '@ns/ui'
interface LayoutProps {
direction?: 'horizontal' | 'vertical'
}
interface HeaderProps {
height?: string | number
}
interface FooterProps {
height?: string | number
}
interface SiderProps {
width?: string | number
collapsedWidth?: string | number
collapsed?: boolean
placement?: 'left' | 'right'
collapsible?: boolean
}
interface ContentProps {}
另外还导出了 SiderInfo、LayoutContext 和注入用的 LAYOUT_INJECTION_KEY,NsSider 通过它向所在的 NsLayout 登记自己,一般用不到。
CSS 变量
这些变量主题里没有预先定义,组件里写了默认值。在 NsLayout 或更外层的元素上设置即可覆盖。
| 变量 | 默认值 | 说明 |
|---|---|---|
--ns-layout-bg-color | var(--ns-bg-color) | NsLayout 的背景色 |
--ns-layout-header-bg-color | var(--ns-bg-color) | 顶栏背景色 |
--ns-layout-header-border-color | var(--ns-border-color-light) | 顶栏下边框颜色 |
--ns-layout-sider-bg-color | var(--ns-bg-color) | 侧边栏背景色 |
--ns-layout-sider-border-color | var(--ns-border-color-light) | 侧边栏边框、触发条上边框 |
--ns-layout-sider-trigger-bg-color | var(--ns-bg-color-hover) | 触发条背景色 |
--ns-layout-sider-trigger-bg-color-hover | var(--ns-color-primary-light-9) | 鼠标悬停时触发条背景色 |
--ns-layout-content-bg-color | var(--ns-bg-color-page) | 内容区背景色 |
--ns-layout-footer-bg-color | var(--ns-bg-color) | 底栏背景色 |
--ns-layout-footer-border-color | var(--ns-border-color-light) | 底栏上边框颜色 |
注意事项
- 不写
direction时,NsLayout里有NsSider就自动横排,没有就竖排。这里的“里面”指离NsSider最近的那个NsLayout,隔着另一个NsLayout的不算。写了direction就以写的为准。 - 侧边栏是在挂载后才向
NsLayout登记的,服务端渲染输出的 HTML 是竖排,到浏览器里挂载后才变成横排。用服务端渲染时显式写上direction="horizontal"。 NsLayout要有确定的高度(例如写死高度、height: 100vh,或者父元素是有高度的 flex 容器),NsContent才能占满剩下的高度、NsSider才能和它等高。高度由内容撑开时,整个布局随内容变高,内容区不会出现自己的滚动条。NsContent内容超出时自己滚动(overflow: auto),顶栏、底栏和侧边栏不动。NsHeader、NsContent、NsFooter都自带 16px 内边距,NsHeader、NsFooter里的内容垂直居中。NsSider必须放在NsLayout里,否则开发环境会打印警告。- 侧边栏没有响应式自动折叠(屏幕变窄时自动收起),需要时自己监听窗口宽度去改
collapsed。 - 只在用户点触发条时才触发
update:collapsed和collapse。在外面改绑定值不会触发这两个事件。 - 只写
:collapsed、不处理update:collapsed时,点触发条仍然会折叠和展开(组件内部会记住状态),绑定值不会变;之后在外面改了这个值,组件再以外面的值为准。 - 折叠只改变侧边栏宽度,不会自动隐藏里面的文字。折叠后要显示成图标,要根据
collapsed自己切换内容,或者配合NsMenu的collapse属性。 - 触发条是一个原生
button,可以用 Tab 键聚焦,按回车或空格切换折叠;它带有aria-expanded,以及“展开侧边栏”“收起侧边栏”的aria-label。