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.
Splitter 分割面板
把一块区域分成几个并排或上下排的面板,拖动面板之间的分隔条调整各面板的大小。
引入
import { NsSplitter, NsSplitterPane } from '@ns/ui'
基础用法
每个面板用一个 NsSplitterPane。面板之间自动加上分隔条,按住分隔条拖动就能调整两边面板的大小。NsSplitter 的宽高都是 100%,外面要给它一个确定的高度。
<script setup lang="ts">
import { NsSplitter, NsSplitterPane } from '@ns/ui'
</script>
<template>
<div style="height: 240px; border: 1px solid var(--ns-border-color)">
<NsSplitter>
<NsSplitterPane>左边</NsSplitterPane>
<NsSplitterPane>右边</NsSplitterPane>
</NsSplitter>
</div>
</template>
没写 size 的面板平分剩下的空间,这里两个面板各占一半。
上下分割
layout="vertical" 时面板上下排列,分隔条是横的,上下拖动。
<template>
<div style="height: 300px">
<NsSplitter layout="vertical">
<NsSplitterPane>上面</NsSplitterPane>
<NsSplitterPane>下面</NsSplitterPane>
</NsSplitter>
</div>
</template>
layout 的两个值放在一起对比:horizontal(默认)左右排、分隔条是竖的;vertical 上下排、分隔条是横的。
<template>
<div class="demo">
<div>
<p class="label">horizontal(默认)</p>
<div class="box">
<NsSplitter>
<NsSplitterPane><div class="pane">左</div></NsSplitterPane>
<NsSplitterPane><div class="pane">右</div></NsSplitterPane>
</NsSplitter>
</div>
</div>
<div>
<p class="label">vertical</p>
<div class="box">
<NsSplitter layout="vertical">
<NsSplitterPane><div class="pane">上</div></NsSplitterPane>
<NsSplitterPane><div class="pane">下</div></NsSplitterPane>
</NsSplitter>
</div>
</div>
</div>
</template>
<style scoped>
.demo {
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: 200px;
border: 1px solid var(--ns-border-color);
}
.pane {
display: flex;
align-items: center;
justify-content: center;
height: 100%;
}
</style>
指定面板大小
size 设置面板的初始大小:数字和不带单位的字符串(如 '200')都是像素,'30%' 这样带百分号的是占容器的百分比。不写 size 的面板平分剩下的空间。
<template>
<div style="height: 240px">
<NsSplitter>
<NsSplitterPane :size="200">固定 200px</NsSplitterPane>
<NsSplitterPane>占满剩下的空间</NsSplitterPane>
<NsSplitterPane size="25%">容器的 25%</NsSplitterPane>
</NsSplitter>
</div>
</template>
拖动后,面板的大小按原来的单位记下来:原来写像素的还是像素,原来写百分比的换算成新的百分比,所以容器尺寸变化时,百分比面板仍然按比例缩放。没写 size 的面板继续填满剩下的空间;相邻两个面板都没写 size 时,拖动后前一个会记成百分比。
size 的三种写法放在一起:
<template>
<div style="height: 160px; border: 1px solid var(--ns-border-color)">
<NsSplitter>
<NsSplitterPane :size="120"><div class="pane">:size="120"</div></NsSplitterPane>
<NsSplitterPane size="160"><div class="pane">size="160"</div></NsSplitterPane>
<NsSplitterPane size="30%"><div class="pane">size="30%"</div></NsSplitterPane>
<NsSplitterPane><div class="pane">不写</div></NsSplitterPane>
</NsSplitter>
</div>
</template>
<style scoped>
.pane {
display: flex;
align-items: center;
justify-content: center;
height: 100%;
white-space: nowrap;
}
</style>
最小和最大尺寸
min-size、max-size 限制拖动时面板能缩到多小、放到多大,单位规则和 size 一样。拖动时相邻两个面板都要满足各自的限制,拖到限制处就停住。
<template>
<div style="height: 240px">
<NsSplitter>
<NsSplitterPane size="30%" min-size="120" max-size="50%">最小 120px,最大 50%</NsSplitterPane>
<NsSplitterPane :min-size="200">最小 200px</NsSplitterPane>
</NsSplitter>
</div>
</template>
上下分割时限制的是高度:
<template>
<div style="height: 300px; border: 1px solid var(--ns-border-color)">
<NsSplitter layout="vertical">
<NsSplitterPane :size="80" :min-size="60" :max-size="160">
<div class="pane">高度 60~160px</div>
</NsSplitterPane>
<NsSplitterPane min-size="30%">
<div class="pane">至少占 30%</div>
</NsSplitterPane>
</NsSplitter>
</div>
</template>
<style scoped>
.pane {
padding: var(--ns-spacing-3);
}
</style>
多个面板
放几个 NsSplitterPane 就分成几块,每两个相邻面板之间一条分隔条。拖动一条分隔条只改变它两边的两个面板,其他面板不动。
<template>
<div style="height: 240px">
<NsSplitter>
<NsSplitterPane size="20%">目录</NsSplitterPane>
<NsSplitterPane>编辑区</NsSplitterPane>
<NsSplitterPane size="25%">预览</NsSplitterPane>
</NsSplitter>
</div>
</template>
嵌套
面板里可以再放一个 NsSplitter,组成左右加上下的布局。内层和外层各管各的面板,互不影响。
<template>
<div style="height: 360px">
<NsSplitter>
<NsSplitterPane size="30%">左侧</NsSplitterPane>
<NsSplitterPane>
<NsSplitter layout="vertical">
<NsSplitterPane>右上</NsSplitterPane>
<NsSplitterPane size="40%">右下</NsSplitterPane>
</NsSplitter>
</NsSplitterPane>
</NsSplitter>
</div>
</template>
面板内容滚动
面板的内容超出面板大小时,在面板里出现滚动条,不会撑大面板。
<template>
<div style="height: 240px; border: 1px solid var(--ns-border-color)">
<NsSplitter>
<NsSplitterPane size="30%">
<p v-for="i in 30" :key="i" style="margin: 0; padding: 4px 12px">文件 {{ i }}.txt</p>
</NsSplitterPane>
<NsSplitterPane>
<div style="padding: 12px">左边的文件列表有 30 项,超出的部分在面板里滚动。</div>
</NsSplitterPane>
</NsSplitter>
</div>
</template>
分隔条粗细和禁止调整
gutter-size 设置分隔条的粗细,单位 px。resizable 为 false 时不显示分隔条,面板直接挨在一起,不能调整大小。
<template>
<NsSpace direction="vertical" fill>
<div style="height: 200px">
<NsSplitter :gutter-size="12">
<NsSplitterPane>左边</NsSplitterPane>
<NsSplitterPane>右边</NsSplitterPane>
</NsSplitter>
</div>
<div style="height: 200px">
<NsSplitter :resizable="false">
<NsSplitterPane size="30%">固定比例</NsSplitterPane>
<NsSplitterPane>不能拖动</NsSplitterPane>
</NsSplitter>
</div>
</NsSpace>
</template>
不同粗细的分隔条放在一起对比。分隔条比 4px 还细时,中间的拖动手柄也跟着变细:
<template>
<NsSpace direction="vertical" fill>
<div v-for="size in [2, 6, 12, 20]" :key="size">
<p class="label">gutter-size {{ size }}{{ size === 6 ? '(默认)' : '' }}</p>
<div class="box">
<NsSplitter :gutter-size="size">
<NsSplitterPane>左边</NsSplitterPane>
<NsSplitterPane>右边</NsSplitterPane>
</NsSplitter>
</div>
</div>
</NsSpace>
</template>
<style scoped>
.label {
margin: 0 0 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.box {
height: 80px;
border: 1px solid var(--ns-border-color);
}
</style>
resizable 可以随时切换,切成 false 时分隔条消失,面板保持当前的大小:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsSplitter, NsSplitterPane, NsSwitch } from '@ns/ui'
const resizable = ref(true)
</script>
<template>
<NsSpace direction="vertical" fill>
<div>
<NsSwitch v-model="resizable" active-text="可以拖动" inactive-text="不能拖动" />
</div>
<div style="height: 200px; border: 1px solid var(--ns-border-color)">
<NsSplitter :resizable="resizable">
<NsSplitterPane size="40%">左边</NsSplitterPane>
<NsSplitterPane>右边</NsSplitterPane>
</NsSplitter>
</div>
</NsSpace>
</template>
自定义颜色
分隔条和拖动手柄的颜色通过 CSS 变量改,见下面的“CSS 变量”。
<template>
<div
style="
height: 200px;
border: 1px solid var(--ns-border-color);
--ns-splitter-gutter-bg: var(--ns-fill-color);
--ns-splitter-gutter-bg-hover: var(--ns-color-success-light);
--ns-splitter-gutter-bg-active: var(--ns-color-success);
--ns-splitter-gutter-handle-bg: var(--ns-color-success);
--ns-splitter-gutter-handle-bg-hover: var(--ns-color-white);
--ns-splitter-gutter-handle-bg-active: var(--ns-color-white);
"
>
<NsSplitter :gutter-size="10">
<NsSplitterPane>悬停、拖动分隔条看颜色变化</NsSplitterPane>
<NsSplitterPane>右边</NsSplitterPane>
</NsSplitter>
</div>
</template>
监听尺寸变化
拖动或用键盘调整时触发 resize,参数是所有面板当前的像素尺寸,按面板的顺序排列,不含分隔条。可以把它存下来,下次作为各面板的 size 传回去,恢复上次的布局。
<script setup lang="ts">
import { computed, ref } from 'vue'
import { NsSplitter, NsSplitterPane } from '@ns/ui'
const sizes = ref<number[]>([240])
const handleResize = (next: number[]) => {
sizes.value = next
}
// 拖动前只知道左边的初始值,拖动后才有两个面板的尺寸
const text = computed(() =>
sizes.value.length > 1
? `各面板尺寸:${sizes.value.map((size) => `${Math.round(size)}px`).join(',')}`
: '拖动分隔条试试'
)
</script>
<template>
<div style="height: 240px">
<NsSplitter @resize="handleResize">
<NsSplitterPane :size="sizes[0]">左边</NsSplitterPane>
<NsSplitterPane>右边</NsSplitterPane>
</NsSplitter>
</div>
<p style="margin-top: 12px">{{ text }}</p>
</template>
双向绑定大小
v-model:size 会记下拖动后的大小,单位和原来一样:写的百分比拖动后还是百分比,写的像素拖动后还是数字。外面再把它设回预设值,面板就恢复。只用 :size 单向传值时,拖动后外面的值没变,设回同一个值面板不会恢复。下面拖动后点按钮改回预设的比例:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsSplitter, NsSplitterPane } from '@ns/ui'
const leftSize = ref<string | number>('30%')
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton @click="leftSize = '20%'">左边 20%</NsButton>
<NsButton @click="leftSize = '30%'">左边 30%(预设)</NsButton>
<NsButton @click="leftSize = '70%'">左边 70%</NsButton>
</NsSpace>
<div style="height: 200px; border: 1px solid var(--ns-border-color)">
<NsSplitter>
<NsSplitterPane v-model:size="leftSize">左边</NsSplitterPane>
<NsSplitterPane>右边</NsSplitterPane>
</NsSplitter>
</div>
<span>左边的 size:{{ typeof leftSize === 'number' ? `${leftSize}px` : leftSize }}</span>
</NsSpace>
</template>
键盘操作
分隔条可以用 Tab 键聚焦。横向分割时按左、右方向键,上下分割时按上、下方向键,每按一次移动 10px,同样受 min-size、max-size 限制。
NsSplitter Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| layout | 'horizontal' | 'vertical' | 'horizontal' | 面板的排列方向。horizontal 左右排,vertical 上下排 |
| gutterSize | number | 6 | 分隔条的粗细,单位 px |
| resizable | boolean | true | 能否调整大小。为 false 时不显示分隔条 |
NsSplitterPane Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| size | string | number | - | 大小,支持 v-model:size。数字和不带单位的字符串是 px,'30%' 是百分比。不写时和其他没写的面板平分剩余空间 |
| minSize | string | number | 0 | 拖动时的最小尺寸,单位规则同 size |
| maxSize | string | number | '100%' | 拖动时的最大尺寸,单位规则同 size |
NsSplitter Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| resize | (sizes: number[]) | 拖动分隔条或用键盘调整时触发。参数是所有面板的像素尺寸,按顺序排列,尺寸没变时不重复触发 |
NsSplitterPane Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:size | (size: string | number) | 拖动或用键盘调整后这个面板的大小,单位和 size 原来的写法一样(百分比或像素数字),用于 v-model:size |
Slots
| 组件 | 插槽 | 作用域参数 | 说明 |
|---|---|---|---|
| NsSplitter | default | - | 放 NsSplitterPane,其他元素不会显示 |
| NsSplitterPane | default | - | 面板的内容,超出面板大小时出现滚动条 |
类型
import type { SplitterProps, SplitterPaneProps, SplitterLayout } from '@ns/ui'
type SplitterLayout = 'horizontal' | 'vertical'
interface SplitterProps {
layout?: SplitterLayout
gutterSize?: number
resizable?: boolean
}
interface SplitterPaneProps {
/** 数字和不带单位的字符串是 px,'30%' 是百分比,不写时平分剩余空间 */
size?: string | number
minSize?: string | number
maxSize?: string | number
}
另外还导出了 PaneInfo、SplitterContext 和注入用的 SPLITTER_INJECTION_KEY,NsSplitterPane 通过它向所在的 NsSplitter 登记自己,一般用不到。
CSS 变量
这些变量主题里没有预先定义,组件里写了默认值,在 NsSplitter 或更外层的元素上设置即可覆盖。分隔条的粗细用 gutterSize 属性设置。
| 变量 | 默认值 | 说明 |
|---|---|---|
--ns-splitter-gutter-bg | var(--ns-border-color-light) | 分隔条背景色 |
--ns-splitter-gutter-bg-hover | var(--ns-color-primary-light) | 鼠标悬停时分隔条背景色 |
--ns-splitter-gutter-bg-active | var(--ns-color-primary) | 拖动时分隔条背景色 |
--ns-splitter-gutter-handle-bg | var(--ns-border-color-hover) | 分隔条正中拖动手柄(24px 长的短条)的颜色 |
--ns-splitter-gutter-handle-bg-hover | var(--ns-color-primary) | 鼠标悬停或键盘聚焦时拖动手柄的颜色 |
--ns-splitter-gutter-handle-bg-active | var(--ns-color-primary) | 拖动时拖动手柄的颜色 |
注意事项
NsSplitter的宽高都是 100%,父元素要有确定的高度,否则上下分割时面板没有高度,左右分割时高度随内容。NsSplitter的直接子元素只能是NsSplitterPane(可以隔着v-for、v-if和<template>)。混在面板之间的其他元素、或者包进自己写的组件里的NsSplitterPane,都不会显示,开发环境会打印一次警告。- 拖动后的大小用
v-model:size同步出来。只写:size时拖动不会改写外面的值,外面改成另一个值时面板按新值显示,设回同一个值不会恢复(值没变)。要拿到所有面板的像素尺寸,用NsSplitter的resize事件。 resize的参数一律是像素,不管面板的size原来写的是像素还是百分比。窗口大小变化引起的面板尺寸变化不触发resize。- 所有面板都写了像素
size、加起来又小于容器时,容器里会空出一块。建议至少留一个面板不写size,让它填满剩下的空间。 - 拖动只在相邻两个面板之间分配空间,两者的总和不变;
min-size、max-size对两个面板同时起作用,任何一个到了限制就拖不动了。 - 没有折叠面板的功能,也不支持双击分隔条复原。
- 分隔条用的是指针事件,鼠标和触摸屏都能拖动。分隔条带
role="separator"、aria-orientation,以及表示前一个面板所占百分比的aria-valuenow、aria-valuemin、aria-valuemax。