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.
Collapse 折叠面板
把内容分成几块,点标题展开或收起,用来在有限的空间里放比较多的内容。每一块用一个 NsCollapseItem。
引入
import { NsCollapse, NsCollapseItem } from '@ns/ui'
基础用法
用 v-model 绑定一个数组,里面是当前展开的面板的 name。可以同时展开多个面板。
<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,全部收起时的值是空字符串。
<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。
<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 时它照样是展开的。
<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>
勾选后第二个面板变成禁用,再点它就没有反应了:
<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。
<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、它现在是不是展开的,以及操作之后所有展开的面板。
<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。
<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' 就对不上。
<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>
收起时保留内容
面板收起时内容只是隐藏,不会销毁。在输入框里输入一些文字,收起再展开,文字还在:
<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,里外两层各自绑定自己的值。
<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 | - | 面板的标题 |
类型
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从绑定值里去掉