Collapse 折叠面板
把内容分成几块,点标题展开或收起,用来在有限的空间里放比较多的内容。每一块用一个 NsCollapseItem。
引入
ts
import { NsCollapse, NsCollapseItem } from '@ns/ui'
基础用法
用 v-model 绑定一个数组,里面是当前展开的面板的 name。可以同时展开多个面板。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsCollapse, NsCollapseItem } from '@ns/ui'
const activeNames = ref<(string | number)[]>(['1'])
</script>
<template>
<NsCollapse v-model="activeNames">
<NsCollapseItem name="1" title="面板一">面板一的内容</NsCollapseItem>
<NsCollapseItem name="2" title="面板二">面板二的内容</NsCollapseItem>
<NsCollapseItem name="3" title="面板三">面板三的内容</NsCollapseItem>
</NsCollapse>
<p style="margin-top: 12px">当前展开:{{ activeNames }}</p>
</template>
手风琴模式
accordion 为 true 时同一时间只展开一个面板,展开另一个时原来的自动收起。这时 v-model 可以直接绑定单个 name,全部收起时的值是空字符串。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsCollapse, NsCollapseItem } from '@ns/ui'
const activeName = ref<string | number>('1')
</script>
<template>
<NsCollapse v-model="activeName" accordion>
<NsCollapseItem name="1" title="面板一">面板一的内容</NsCollapseItem>
<NsCollapseItem name="2" title="面板二">面板二的内容</NsCollapseItem>
<NsCollapseItem name="3" title="面板三">面板三的内容</NsCollapseItem>
</NsCollapse>
<p style="margin-top: 12px">
当前展开:{{ activeName === '' ? '空字符串(全部收起)' : activeName }}
</p>
</template>
手风琴模式下也可以照旧绑定数组,这时数组里最多有一个 name。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsCollapse, NsCollapseItem } from '@ns/ui'
const activeNames = ref<(string | number)[]>(['1'])
</script>
<template>
<NsCollapse v-model="activeNames" accordion>
<NsCollapseItem name="1" title="面板一">面板一的内容</NsCollapseItem>
<NsCollapseItem name="2" title="面板二">面板二的内容</NsCollapseItem>
</NsCollapse>
<p style="margin-top: 12px">当前展开:{{ activeNames }}</p>
</template>
禁用面板
NsCollapseItem 的 disabled 为 true 时,这个面板不能点击,也不能用键盘聚焦。禁用只影响用户操作,绑定值里有它的 name 时它照样是展开的。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsCollapse, NsCollapseItem } from '@ns/ui'
const activeNames = ref<(string | number)[]>(['1', '3'])
</script>
<template>
<NsCollapse v-model="activeNames">
<NsCollapseItem name="1" title="可以操作的面板">内容</NsCollapseItem>
<NsCollapseItem name="2" title="禁用,收起状态" disabled>内容</NsCollapseItem>
<NsCollapseItem name="3" title="禁用,展开状态" disabled>内容</NsCollapseItem>
</NsCollapse>
</template>
勾选后第二个面板变成禁用,再点它就没有反应了:
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsCollapse, NsCollapseItem } from '@ns/ui'
const disabled = ref(false)
const activeNames = ref<(string | number)[]>([])
</script>
<template>
<NsCheckbox v-model="disabled">禁用面板二</NsCheckbox>
<NsCollapse v-model="activeNames" style="margin-top: 12px">
<NsCollapseItem name="1" title="面板一">面板一的内容</NsCollapseItem>
<NsCollapseItem name="2" title="面板二" :disabled="disabled">面板二的内容</NsCollapseItem>
</NsCollapse>
</template>
自定义标题
标题要放图标、标签、按钮时用 title 插槽,写了插槽以后不再显示 title 属性。标题里的按钮不想触发展开、收起时,点击事件加 .stop。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsCollapse, NsCollapseItem, NsIcon, NsButton, NsTag } from '@ns/ui'
const activeNames = ref<(string | number)[]>(['1'])
const editCount = ref(0)
const handleEdit = () => {
editCount.value += 1
}
</script>
<template>
<NsCollapse v-model="activeNames">
<NsCollapseItem name="1">
<template #title>
<NsIcon name="setting" />
<span style="margin-left: 8px">系统设置</span>
</template>
内容
</NsCollapseItem>
<NsCollapseItem name="2">
<template #title>
<span style="flex: 1">带操作按钮的标题</span>
<NsButton size="small" @click.stop="handleEdit">编辑</NsButton>
</template>
点了 {{ editCount }} 次“编辑”,面板没有因此展开或收起
</NsCollapseItem>
<NsCollapseItem name="3">
<template #title>
<span style="margin-right: 8px">待办事项</span>
<NsTag type="danger" size="small" round>3</NsTag>
</template>
标题里放标签
</NsCollapseItem>
</NsCollapse>
</template>
监听展开和收起
用户点面板时触发 change,参数里有这次操作的面板 name、它现在是不是展开的,以及操作之后所有展开的面板。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsCollapse, NsCollapseItem } from '@ns/ui'
import type { CollapseChangeEvent } from '@ns/ui'
const activeNames = ref<(string | number)[]>([])
const log = ref('')
const handleChange = (event: CollapseChangeEvent) => {
log.value = `面板 ${event.name} ${event.expanded ? '展开了' : '收起了'},现在展开的是 [${event.activeNames.join(', ')}]`
}
</script>
<template>
<NsCollapse v-model="activeNames" @change="handleChange">
<NsCollapseItem name="a" title="面板 A">内容 A</NsCollapseItem>
<NsCollapseItem name="b" title="面板 B">内容 B</NsCollapseItem>
</NsCollapse>
<p style="margin-top: 12px">{{ log || '点面板标题试试' }}</p>
</template>
用代码控制
改 v-model 绑定的值就可以展开、收起面板。直接改绑定值不触发 change。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCollapse, NsCollapseItem, NsSpace } from '@ns/ui'
const activeNames = ref<(string | number)[]>([])
</script>
<template>
<div style="margin-bottom: 12px">
<NsSpace wrap>
<NsButton @click="activeNames = ['1', '2', '3']">全部展开</NsButton>
<NsButton @click="activeNames = []">全部收起</NsButton>
<NsButton @click="activeNames = ['2']">只展开面板二</NsButton>
</NsSpace>
</div>
<NsCollapse v-model="activeNames">
<NsCollapseItem name="1" title="面板一">内容一</NsCollapseItem>
<NsCollapseItem name="2" title="面板二">内容二</NsCollapseItem>
<NsCollapseItem name="3" title="面板三">内容三</NsCollapseItem>
</NsCollapse>
</template>
数字作为 name
name 也可以是数字,写成 :name="1"。绑定值里的类型要和面板上的一致:下面绑定值里是数字 1,所以第一个面板展开;如果写成字符串 '1' 就对不上。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsCollapse, NsCollapseItem } from '@ns/ui'
const activeNames = ref<(string | number)[]>([1])
</script>
<template>
<NsCollapse v-model="activeNames">
<NsCollapseItem v-for="i in 3" :key="i" :name="i" :title="`面板 ${i}`">
面板 {{ i }} 的内容
</NsCollapseItem>
</NsCollapse>
<p style="margin-top: 12px">当前展开:{{ activeNames }}</p>
</template>
收起时保留内容
面板收起时内容只是隐藏,不会销毁。在输入框里输入一些文字,收起再展开,文字还在:
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsCollapse, NsCollapseItem, NsInput } from '@ns/ui'
const activeNames = ref<(string | number)[]>(['form'])
const remark = ref('')
</script>
<template>
<NsCollapse v-model="activeNames">
<NsCollapseItem name="form" title="填写备注">
<NsInput v-model="remark" placeholder="输入后收起再展开" />
</NsCollapseItem>
</NsCollapse>
</template>
嵌套
面板的内容里可以再放一个 NsCollapse,里外两层各自绑定自己的值。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsCollapse, NsCollapseItem } from '@ns/ui'
const outer = ref<(string | number)[]>(['1'])
const inner = ref<(string | number)[]>([])
</script>
<template>
<NsCollapse v-model="outer">
<NsCollapseItem name="1" title="外层面板">
<NsCollapse v-model="inner">
<NsCollapseItem name="1-1" title="内层面板一">内层内容一</NsCollapseItem>
<NsCollapseItem name="1-2" title="内层面板二">内层内容二</NsCollapseItem>
</NsCollapse>
</NsCollapseItem>
<NsCollapseItem name="2" title="另一个外层面板">内容</NsCollapseItem>
</NsCollapse>
<p style="margin-top: 12px">外层:{{ outer }},内层:{{ inner }}</p>
</template>
NsCollapse Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | CollapseName | CollapseName[] | [] | 当前展开的面板的 name,支持 v-model。一般传数组;手风琴模式下可以传单个 name |
| accordion | boolean | false | 是否手风琴模式(同一时间只展开一个) |
NsCollapseItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| name | string | number | - | 必填。面板的唯一标识,同一个 NsCollapse 里不能重复 |
| title | string | '' | 标题文字。写了 title 插槽时不显示 |
| disabled | boolean | false | 是否禁用。禁用后不能点击和聚焦 |
NsCollapse Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: CollapseName | CollapseName[]) | 用户展开或收起面板时触发,v-model 用的就是它。手风琴模式并且传进来的不是数组时,回传单个 name(全部收起时是空字符串),其他情况回传数组 |
| change | (event: CollapseChangeEvent) | 用户展开或收起面板时触发。event.name 是操作的面板,event.expanded 是它现在是否展开,event.activeNames 是操作后所有展开的面板(始终是数组) |
NsCollapse Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsCollapseItem |
NsCollapseItem Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 面板的内容 |
| title | - | 面板的标题 |
类型
ts
import type {
CollapseName,
CollapseModelValue,
CollapseChangeEvent,
CollapseProps,
CollapseItemProps
} from '@ns/ui'
type CollapseName = string | number
type CollapseModelValue = CollapseName | CollapseName[]
interface CollapseChangeEvent {
activeNames: (string | number)[]
expanded: boolean
name: string | number
}
interface CollapseProps {
modelValue?: CollapseModelValue
accordion?: boolean
}
interface CollapseItemProps {
name: string | number
title?: string
disabled?: boolean
}
另外还导出了 CollapseContext 和注入用的 COLLAPSE_INJECTION_KEY,自己写和 NsCollapse 配合的子组件时才用得到。
注意事项
name按严格相等比较,'1'和1是两个不同的面板。绑定值里的类型要和NsCollapseItem上写的一致:name="1"是字符串,:name="1"是数字。- 手风琴模式下绑定值是数组并且有多个
name时,只展开第一个。运行中把accordion改成true也只保留第一个,但这时不会触发update:modelValue,绑定值要到用户下一次操作才更新。 change只在用户点击或按键操作时触发,直接改绑定值不触发。- 面板被移除后(例如
v-for的数据删掉一项),它的name还留在绑定值里,需要时自己清掉。 - 面板收起时内容只是隐藏,不会销毁,里面的表单输入等状态会保留。
- 焦点在标题栏上时按回车或空格可以切换。焦点在标题插槽里的按钮、输入框上时,按键归它们自己处理。
- 手风琴模式下外层没有边框,这是现有的样式。
优化点
- [x] 支持面板动画效果优化:展开、收起有高度过渡
- [x] 支持面板嵌套使用
- [ ] 支持面板图标自定义
- [ ] 支持箭头放在标题左边
- [ ] 支持展开前的拦截(
beforeCollapse) - [ ] 面板移除时自动把它的
name从绑定值里去掉