Tabs 标签页
把内容分成几个面板,同一时间只显示一个,点标签切换。每个面板用一个 NsTabPane。
引入
import { NsTabs, NsTabPane } from '@ns/ui'
基础用法
v-model 绑定当前激活的面板的 name。NsTabPane 的 label 是标签文字,默认插槽是面板内容。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane } from '@ns/ui'
const activeName = ref<string | number>('user')
</script>
<template>
<NsTabs v-model="activeName">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理">角色管理的内容</NsTabPane>
</NsTabs>
<p style="margin-top: 12px">当前激活:{{ activeName }}</p>
</template>
类型
type 可选:
line(默认):标签栏下面有一条细分隔线,激活的标签下面有一条主色的线。card:每个标签带边框,激活的标签和下面的内容区连在一起。border-card:整个标签页带边框,内容区也在边框里,标签栏是浅灰色底。button:标签显示成一排相连的按钮,外观和单选框组的按钮样式(NsRadioGroup type="button")一样,激活的标签是主色填充、白字。没有激活条和分隔线,标签栏和内容区之间留 12px 间距。
下面四个标签页绑定同一个值,切换任意一个,其他的跟着变:
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane, NsSpace } from '@ns/ui'
const activeName = ref<string | number>('user')
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<div>
<p class="row-label">line</p>
<NsTabs v-model="activeName" type="line">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理" disabled>角色管理的内容</NsTabPane>
</NsTabs>
</div>
<div>
<p class="row-label">card</p>
<NsTabs v-model="activeName" type="card">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理" disabled>角色管理的内容</NsTabPane>
</NsTabs>
</div>
<div>
<p class="row-label">border-card</p>
<NsTabs v-model="activeName" type="border-card">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理" disabled>角色管理的内容</NsTabPane>
</NsTabs>
</div>
<div>
<p class="row-label">button</p>
<NsTabs v-model="activeName" type="button">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理" disabled>角色管理的内容</NsTabPane>
</NsTabs>
</div>
</NsSpace>
</template>
<style scoped>
.row-label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
按钮样式的细节:
- 按钮的高度、内边距、圆角跟着
size变(见下面的“不同尺寸”),default 时高 32px,和默认尺寸的按钮、输入框对齐;只有整排两头有圆角。 - 禁用的标签半透明显示。
tab-position为left、right时按钮竖着排,为bottom时按钮栏在内容区下面。- 可关闭时关闭图标在按钮里文字的右边;新增按钮是一个同样高、带边框的方形按钮。
stretch时按钮平分整行宽度;标签放不下时和其他风格一样可以滚动。
不同尺寸
size 可选 large、default、small,四种 type、四个方向都适用。不写时跟随 NsConfigProvider 的 size,再没有就是 default。NsTabs 不是表单控件,放在 NsForm 里不跟随表单的尺寸。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane, NsSpace } from '@ns/ui'
const activeName = ref<string | number>('user')
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<div>
<p class="row-label">large</p>
<NsTabs v-model="activeName" size="large">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
</NsTabs>
</div>
<div>
<p class="row-label">default</p>
<NsTabs v-model="activeName" size="default">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
</NsTabs>
</div>
<div>
<p class="row-label">small</p>
<NsTabs v-model="activeName" size="small">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
</NsTabs>
</div>
</NsSpace>
</template>
<style scoped>
.row-label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
切换尺寸,看其他几种样式(带关闭和新增按钮)的变化:
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsRadioGroup, NsSpace, NsTabPane, NsTabs } from '@ns/ui'
import type { TabsSize } from '@ns/ui'
const size = ref<TabsSize>('small')
const activeName = ref<string | number>('user')
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsRadioGroup v-model="size" type="button" size="small">
<NsRadio value="large">large</NsRadio>
<NsRadio value="default">default</NsRadio>
<NsRadio value="small">small</NsRadio>
</NsRadioGroup>
<NsTabs v-model="activeName" type="card" :size="size" editable>
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
</NsTabs>
<NsTabs v-model="activeName" type="border-card" :size="size">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
</NsTabs>
<NsTabs v-model="activeName" type="button" :size="size" closable>
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
</NsTabs>
</NsSpace>
</template>
三档的取值:
| 项目 | large | default | small |
|---|---|---|---|
| 字号 | 16px | 14px | 12px |
line、card、border-card 的标签内边距 | 上下 10、左右 16 | 上下 8、左右 12 | 上下 6、左右 8 |
line、card、border-card 的标签高(约) | 44px | 37px | 30px |
button 的按钮高 | 40px | 32px | 24px |
button 的按钮左右内边距 | 20px | 16px | 12px |
外侧圆角(card、border-card、button) | 8px | 6px | 4px |
| 关闭按钮 / 叉号 | 18px / 16px | 16px / 14px | 14px / 12px |
| 滚动箭头、新增按钮的加号 | 16px | 14px | 12px |
border-card 内容区内边距 | 20px | 16px | 12px |
button 样式的新增按钮是和按钮一样高的方形按钮,small 的 border-card 标签栏内边距收到 4px。标签栏和内容区之间的 12px 间距三档一样。
标签位置
tab-position 可选 top(默认)、bottom、left、right。放在左右两边时标签竖着排。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane } from '@ns/ui'
const activeName = ref<string | number>('user')
</script>
<template>
<div class="grid">
<div>
<p class="row-label">top</p>
<NsTabs v-model="activeName" tab-position="top">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理">角色管理的内容</NsTabPane>
</NsTabs>
</div>
<div>
<p class="row-label">bottom</p>
<NsTabs v-model="activeName" tab-position="bottom">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理">角色管理的内容</NsTabPane>
</NsTabs>
</div>
<div>
<p class="row-label">left</p>
<NsTabs v-model="activeName" tab-position="left" style="height: 160px">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理">角色管理的内容</NsTabPane>
</NsTabs>
</div>
<div>
<p class="row-label">right</p>
<NsTabs v-model="activeName" tab-position="right" style="height: 160px">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理">角色管理的内容</NsTabPane>
</NsTabs>
</div>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
gap: 24px;
}
.row-label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
四个方向和四种样式都能搭配,切换看看:
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsRadioGroup, NsSpace, NsTabPane, NsTabs } from '@ns/ui'
import type { TabsPosition, TabsType } from '@ns/ui'
const activeName = ref<string | number>('user')
const position = ref<TabsPosition>('left')
const type = ref<TabsType>('card')
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSpace wrap>
<NsRadioGroup v-model="position" type="button" size="small">
<NsRadio value="top">top</NsRadio>
<NsRadio value="right">right</NsRadio>
<NsRadio value="bottom">bottom</NsRadio>
<NsRadio value="left">left</NsRadio>
</NsRadioGroup>
<NsRadioGroup v-model="type" type="button" size="small">
<NsRadio value="line">line</NsRadio>
<NsRadio value="card">card</NsRadio>
<NsRadio value="border-card">border-card</NsRadio>
<NsRadio value="button">button</NsRadio>
</NsRadioGroup>
</NsSpace>
<NsTabs v-model="activeName" :tab-position="position" :type="type" style="height: 200px">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理">角色管理的内容</NsTabPane>
</NsTabs>
</NsSpace>
</template>
禁用标签
NsTabPane 的 disabled 为 true 时,这个标签不能点击,键盘操作时也会跳过它;可关闭时也不显示关闭按钮。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane, NsSpace } from '@ns/ui'
const activeName = ref<string | number>('user')
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsTabs v-model="activeName">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理" disabled>配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理">角色管理的内容</NsTabPane>
</NsTabs>
<NsTabs v-model="activeName" type="card" closable>
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理(禁用)" disabled>配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理">角色管理的内容</NsTabPane>
</NsTabs>
</NsSpace>
</template>
标签撑满
stretch 为 true 时,标签平分标签栏的宽度,各种样式都适用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane, NsSpace } from '@ns/ui'
const activeName = ref<string | number>('user')
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsTabs v-model="activeName" stretch>
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理">角色管理的内容</NsTabPane>
</NsTabs>
<NsTabs v-model="activeName" type="button" stretch>
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理">角色管理的内容</NsTabPane>
</NsTabs>
</NsSpace>
</template>
不指定激活项
没绑定 v-model,或者绑定的值是 undefined 时,自动激活第一个没有禁用的标签,并通过 update:modelValue 把它的 name 传出来。NsTabPane 没写 name 时,按它在标签里的顺序用 '0'、'1'、'2' 作为 name。
<template>
<NsTabs>
<NsTabPane label="第一个">第一个面板</NsTabPane>
<NsTabPane label="第二个">第二个面板</NsTabPane>
</NsTabs>
</template>
下面第一个标签是禁用的,所以自动激活第二个,绑定值收到的是 '1':
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane } from '@ns/ui'
const activeName = ref<string | number>()
</script>
<template>
<NsTabs v-model="activeName">
<NsTabPane label="禁用的" disabled>禁用的面板</NsTabPane>
<NsTabPane label="第二个">第二个面板</NsTabPane>
<NsTabPane label="第三个">第三个面板</NsTabPane>
</NsTabs>
<p style="margin-top: 12px">绑定值:{{ activeName }}</p>
</template>
可关闭
closable 给每个标签加上关闭按钮。点关闭按钮时触发 tab-remove,组件不会自己删掉面板,要在事件里把它从数据里去掉。某个标签不让关闭时,在 NsTabPane 上写 :closable="false"。
关闭的是当前激活的标签时,会自动激活它后面的标签;后面没有,就激活前面的;禁用的标签会被跳过。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane } from '@ns/ui'
const activeName = ref<string | number>('home')
const tabs = ref([
{ name: 'home', label: '首页', closable: false },
{ name: 'user', label: '用户管理', closable: true },
{ name: 'role', label: '角色管理', closable: true }
])
const removed = ref<Array<string | number>>([])
const handleRemove = (name: string | number) => {
tabs.value = tabs.value.filter((tab) => tab.name !== name)
removed.value.push(name)
}
</script>
<template>
<NsTabs v-model="activeName" type="card" closable @tab-remove="handleRemove">
<NsTabPane
v-for="tab in tabs"
:key="tab.name"
:name="tab.name"
:label="tab.label"
:closable="tab.closable"
>
{{ tab.label }}的内容
</NsTabPane>
</NsTabs>
<p style="margin-top: 12px">
当前激活:{{ activeName }};已关闭:{{ removed.length ? removed.join('、') : '无' }}
</p>
</template>
可新增和关闭
addable 在标签栏末尾显示一个加号按钮,点了触发 tab-add。editable 等于同时打开 closable 和 addable。新增的标签要自己加到数据里,需要的话顺便把它设成激活项。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane } from '@ns/ui'
let seed = 2
const activeName = ref<string | number>('tab-1')
const tabs = ref([
{ name: 'tab-1', label: '标签 1' },
{ name: 'tab-2', label: '标签 2' }
])
const handleAdd = () => {
seed += 1
const name = `tab-${seed}`
tabs.value = [...tabs.value, { name, label: `标签 ${seed}` }]
activeName.value = name
}
const handleRemove = (name: string | number) => {
tabs.value = tabs.value.filter((tab) => tab.name !== name)
}
</script>
<template>
<NsTabs v-model="activeName" type="card" editable @tab-add="handleAdd" @tab-remove="handleRemove">
<NsTabPane v-for="tab in tabs" :key="tab.name" :name="tab.name" :label="tab.label">
{{ tab.label }}的内容
</NsTabPane>
</NsTabs>
</template>
只写 addable 时只能新增、不能关闭,按钮样式下新增按钮是一个同样高的方形按钮:
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane } from '@ns/ui'
const activeName = ref<string | number>(1)
const count = ref(2)
const handleAdd = () => {
count.value += 1
activeName.value = count.value
}
</script>
<template>
<NsTabs v-model="activeName" type="button" addable @tab-add="handleAdd">
<NsTabPane v-for="index in count" :key="index" :name="index" :label="`方案 ${index}`">
方案 {{ index }} 的内容
</NsTabPane>
</NsTabs>
</template>
标签很多时
标签放不下时,标签栏两端出现箭头按钮,点了向前、向后滚动;横向的标签栏还可以用鼠标滚轮滚动。激活的标签不在可见范围内时会自动滚到能看见的位置。标签放在左右两边时,要给 NsTabs 设一个高度才会出现滚动。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane, NsSpace } from '@ns/ui'
const activeName = ref<string | number>(1)
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsTabs v-model="activeName">
<NsTabPane v-for="index in 30" :key="index" :name="index" :label="`标签 ${index}`">
第 {{ index }} 个面板
</NsTabPane>
</NsTabs>
<NsTabs v-model="activeName" tab-position="left" style="height: 200px">
<NsTabPane v-for="index in 30" :key="index" :name="index" :label="`标签 ${index}`">
第 {{ index }} 个面板
</NsTabPane>
</NsTabs>
</NsSpace>
</template>
自定义标签
标签里要放图标、徽标等内容时用 NsTabPane 的 label 插槽。label 属性也可以直接传 VNode。
<script setup lang="ts">
import { h, ref } from 'vue'
import { NsTabs, NsTabPane, NsIcon, NsBadge } from '@ns/ui'
const activeName = ref<string | number>('user')
const mailLabel = h('span', [h(NsIcon, { name: 'mail' }), ' 站内信'])
</script>
<template>
<NsTabs v-model="activeName">
<NsTabPane name="user">
<template #label>
<NsIcon name="user" />
<span style="margin-left: 4px">用户管理</span>
</template>
用户管理的内容
</NsTabPane>
<NsTabPane name="setting">
<template #label>
<NsIcon name="setting" />
<span style="margin-left: 4px">系统设置</span>
</template>
系统设置的内容
</NsTabPane>
<NsTabPane name="todo">
<template #label>
<NsBadge :value="5">
<span style="padding-right: 8px">待办</span>
</NsBadge>
</template>
待办的内容
</NsTabPane>
<NsTabPane name="mail" :label="mailLabel">label 传 VNode</NsTabPane>
</NsTabs>
</template>
延迟渲染
默认所有面板的内容在一开始就渲染好,没激活的只是隐藏。NsTabPane 加上 lazy 后,这个面板的内容等到第一次激活时才渲染,适合内容比较重、或者一渲染就要请求数据的面板。不管是不是 lazy,渲染过的面板切走后都不会销毁,里面的状态会保留。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane } from '@ns/ui'
const activeName = ref<string | number>('basic')
</script>
<template>
<NsTabs v-model="activeName">
<NsTabPane name="basic" label="基本信息">一开始就渲染</NsTabPane>
<NsTabPane name="log" label="操作日志" lazy>第一次点到这个标签时才渲染</NsTabPane>
</NsTabs>
</template>
切换前拦截
before-leave 在切换标签之前调用,参数是要切换到的 name 和当前的 name。返回 false,或者返回的 Promise 结果是 false、被拒绝时,不切换。关闭当前标签引起的切换不会调用 before-leave,要拦截关闭,在 tab-remove 的处理函数里自己决定删不删。
下面打开“表单有改动”后,离开“编辑表单”会被拦住;切到“发布”时先校验 1 秒,返回的 Promise 结果是 true 才切过去:
<script setup lang="ts">
import { ref } from 'vue'
import { NsMessage, NsSpace, NsSwitch, NsTabPane, NsTabs } from '@ns/ui'
const activeName = ref<string | number>('form')
const dirty = ref(true)
const beforeLeave = (newName: string | number, oldName: string | number) => {
if (oldName === 'form' && dirty.value) {
NsMessage.warning('表单还没保存,不能离开')
return false
}
if (newName === 'publish') {
return new Promise<boolean>((resolve) => {
NsMessage.info('正在校验…')
setTimeout(() => resolve(true), 1000)
})
}
return true
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSwitch v-model="dirty" active-text="表单有改动" />
<NsTabs v-model="activeName" :before-leave="beforeLeave">
<NsTabPane name="form" label="编辑表单">表单内容</NsTabPane>
<NsTabPane name="preview" label="预览">预览内容</NsTabPane>
<NsTabPane name="publish" label="发布">发布设置</NsTabPane>
</NsTabs>
</NsSpace>
</template>
监听点击
用户点标签时触发 tab-click,参数是这个标签的信息。点的是当前已激活的标签也会触发,点禁用的标签不触发。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTabs, NsTabPane } from '@ns/ui'
import type { TabPaneInstance } from '@ns/ui'
const activeName = ref<string | number>('user')
const clicked = ref('')
const handleTabClick = (tab: TabPaneInstance) => {
clicked.value = `${tab.label}(name:${tab.name})`
}
</script>
<template>
<NsTabs v-model="activeName" @tab-click="handleTabClick">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理" disabled>角色管理的内容</NsTabPane>
</NsTabs>
<p style="margin-top: 12px">最近点击:{{ clicked || '无' }}</p>
</template>
读取标签信息
NsTabs 通过 ref 暴露 activeName(当前激活的 name)和 panes(所有标签的信息,顺序和显示的顺序一致)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsTabPane, NsTabs } from '@ns/ui'
const tabsRef = ref<InstanceType<typeof NsTabs>>()
const activeName = ref<string | number>('user')
const info = ref('')
const read = () => {
const panes = tabsRef.value?.panes ?? []
const names = panes.map((pane) => `${pane.name}${pane.disabled ? '(禁用)' : ''}`)
info.value = `activeName:${tabsRef.value?.activeName};panes:${names.join('、')}`
}
</script>
<template>
<NsTabs ref="tabsRef" v-model="activeName">
<NsTabPane name="user" label="用户管理">用户管理的内容</NsTabPane>
<NsTabPane name="config" label="配置管理">配置管理的内容</NsTabPane>
<NsTabPane name="role" label="角色管理" disabled>角色管理的内容</NsTabPane>
</NsTabs>
<p style="margin-top: 12px">
<NsButton size="small" @click="read">读取</NsButton>
<span style="margin-left: 8px">{{ info }}</span>
</p>
</template>
NsTabs Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | number | - | 当前激活的面板的 name,支持 v-model。不传时自动激活第一个没有禁用的标签 |
| type | 'line' | 'card' | 'border-card' | 'button' | 'line' | 标签的样式,button 是一排相连的按钮 |
| tabPosition | 'top' | 'right' | 'bottom' | 'left' | 'top' | 标签栏的位置 |
| stretch | boolean | false | 标签是否平分标签栏的宽度 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不写时跟随 NsConfigProvider 的 size,再没有就是 default |
| closable | boolean | false | 标签是否带关闭按钮 |
| addable | boolean | false | 是否显示新增按钮 |
| editable | boolean | false | 同时打开 closable 和 addable |
| beforeLeave | (activeName: string | number, oldActiveName: string | number) => boolean | Promise<boolean> | - | 切换标签前调用。返回 false、Promise 结果是 false 或被拒绝时不切换;关闭标签引起的切换不调用 |
NsTabPane Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| name | string | number | - | 面板的标识,对应 NsTabs 的绑定值。不写时按顺序用 '0'、'1'…… |
| label | string | VNode | - | 标签文字。写了 label 插槽时不显示 |
| disabled | boolean | false | 是否禁用。禁用的标签不能点击、不能关闭 |
| closable | boolean | true | 这个标签能不能关闭。只有 NsTabs 打开了 closable 或 editable 时才起作用 |
| lazy | boolean | false | 是否等到第一次激活时才渲染面板内容 |
NsTabs Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string | number) | 激活的标签变化时触发,v-model 用的就是它。包括用户切换、自动激活第一个标签、关闭当前标签后激活相邻标签 |
| tab-click | (tab: TabPaneInstance) | 用户点标签(或在标签上按回车、空格)时触发,点的是当前已激活的标签、或者切换被 beforeLeave 拦住时也会触发。点禁用的标签不触发 |
| tab-remove | (name: string | number) | 用户点标签的关闭按钮(或在标签上按 Delete、Backspace)时触发,参数是这个标签的 name |
| tab-add | - | 用户点新增按钮时触发 |
NsTabs Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsTabPane。其他内容会原样显示在内容区里,不生成标签 |
NsTabPane Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 面板的内容 |
| label | - | 标签的内容 |
NsTabs 暴露的属性
通过组件的 ref 读取。NsTabs 没有可调用的方法,只有两个只读用的状态:
| 属性 | 类型 | 说明 |
|---|---|---|
| activeName | string | number | undefined | 当前激活的标签的 name |
| panes | TabPaneInstance[] | 当前所有标签的信息,顺序和显示的顺序一致 |
类型
import type {
TabsProps,
TabPaneProps,
TabsType,
TabsPosition,
TabsSize,
TabPaneInstance
} from '@ns/ui'
import type { Ref, VNode } from 'vue'
type TabsType = 'line' | 'card' | 'border-card' | 'button'
type TabsPosition = 'top' | 'right' | 'bottom' | 'left'
type TabsSize = 'large' | 'default' | 'small'
interface TabsProps {
modelValue?: string | number
type?: TabsType
closable?: boolean
addable?: boolean
editable?: boolean
tabPosition?: TabsPosition
stretch?: boolean
size?: TabsSize
beforeLeave?: (
activeName: string | number,
oldActiveName: string | number
) => boolean | Promise<boolean>
}
interface TabPaneProps {
label?: string | VNode
name?: string | number
disabled?: boolean
closable?: boolean
lazy?: boolean
}
/** tab-click 事件的参数、ref 上 panes 里的每一项 */
interface TabPaneInstance {
name: string | number
label: string | VNode
disabled: boolean
closable: boolean
lazy: boolean
rendered: Ref<boolean>
}
另外还导出了 TabsContext 和注入用的 TABS_INJECTION_KEY,自己写和 NsTabs 配合的子组件时才用得到。
注意事项
NsTabPane必须直接放在NsTabs的默认插槽里(可以隔着v-for、v-if和<template>)。把NsTabPane包进自己写的组件再放进来,不会生成标签。- 标签的顺序就是
NsTabPane在模板里的顺序。 name按严格相等比较,'1'和1不是同一个标签。name="1"是字符串,:name="1"是数字,绑定值的类型要和它一致。- 绑定值指向一个不存在的标签时,没有标签是激活的,内容区是空的,组件不会自动改成别的标签。
- 关闭标签只触发
tab-remove,面板要自己从数据里删。关闭当前激活的标签后自动激活相邻标签(跳过禁用的),这一步不经过beforeLeave。禁用的标签不显示关闭按钮。 - 把最后一个标签也关掉后,没有标签是激活的,这时不会触发
update:modelValue,绑定值还留着被关掉的那个name。之后再新增标签时,要自己把绑定值设成新标签的name。 - 键盘操作:Tab 键聚焦到标签后,方向键在没有禁用的标签之间移动焦点,回车或空格激活,可关闭的标签按 Delete 或 Backspace 关闭。新增按钮也可以聚焦,按回车或空格触发。
- 默认(不加
lazy)时所有面板的内容一开始就渲染,面板里的组件都会挂载、发请求。面板多或者内容重时给它们加上lazy。
优化点
- [ ] 关闭最后一个标签时通知使用方(现在
update:modelValue的参数类型不允许传undefined) - [ ] 支持切走后销毁面板内容(如
destroy-on-hide) - [ ] 支持标签拖拽排序
- [ ] 支持在标签栏右侧放自定义内容的插槽
- [ ] 标签和面板之间补上
aria-controls/aria-labelledby的对应关系