Collapsible 折叠面板
单面板自折叠原语:无容器、自管开合的独立折叠块。与 oas-collapse 的关系——collapse 是「容器 + 多面板」的编排件,面板开合由容器驱动;collapsible 是独立单面板,适合文件树节点、表单折叠分区、侧栏分组等「一个区块自己开合」的场景。
基础用法
点击触发器开合
展开后显示更多筛选条件:日期范围、标签、负责人等。
默认收起;点击触发器区域切换开合,展开态由组件自管(非受控)。
非受控初值
default-open 默认展开
首帧按 default-open 展开,之后状态由组件自管,不写回任何属性。
default-open 只作非受控初值;一旦设置 open 属性则进入受控模式,default-open 不再生效。
受控模式
open 受控 + oas-toggle 事件
受控模式:open 属性在场时显示值跟属性走(值非 false 为展开);点击后组件写回属性并派发事件。
当前状态:展开
受控契约:open 属性在场 = 受控(open 或值非 "false" 为展开、open="false" 为收起);点击翻转后组件写回 open 属性并派发 oas-toggle(乐观更新)。宿主移除 open 属性即回到非受控,内部状态播种为移除前显示值,不跳变。
框架绑定注意:
open的值语义在 Vue CSR / React / 手写 HTML 下均可正确表达(框架会把:open="false"序列化为open="false")。但 Vue SSR/SSG(含 Nuxt、Vitepress 构建期)会把布尔false归一化为「移除属性」(open是 HTML 布尔属性名)——SSR 直出的受控收起会退化为非受控,字符串"false"绑定会被归一化为无值open(展开)。SSR 宿主建议用静态属性声明初始态 + 监听oas-toggle在客户端接管状态,或宿主框架侧改用 JS property(el.open = false)绑定。
事件
oas-toggle 在每次开合后派发,detail: { open };受控与非受控模式均派发。
禁用
disabled 禁用触发器
禁用态:触发器不可聚焦、不可点击,不派发事件。
disabled 置灰展示;config-provider 全局禁用注入同样生效。
富触发内容
slot="header" 自定义触发器
触发内容来自 slot="header",优先于 header 属性文案;可放图标、标签等任意内容。
自定义展开图标
template[slot="toggle"] 自定义展开图标
展开图标替换为向下的 chevron,收起时随展开态旋转。
表单折叠分区
场景:设置页折叠分区
邮件通知、桌面通知与免打扰时段等设置项。
可见范围、数据共享与历史记录清理等设置项。
多个 collapsible 各自独立开合(无手风琴互斥——互斥编排请用 oas-collapse accordion)。
无 JS 退化
组件未升级(无 JS 环境)时,light DOM 内容作为普通内容直接可见——折叠能力退化、信息不丢失。
API
oas-collapsible
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
default-open | 非受控初始展开(值语义:非 "false" 为展开,兼容框架布尔绑定序列化出的 "false" 在场写法):首帧初值,之后组件自管,不写回属性;open 属性在场时失效(进入受控) | — | — |
disabled | 禁用触发器:不可聚焦、不可点击、不派发事件;config-provider 全局禁用注入同样生效 | boolean | — |
header | 触发器文案(渲染进触发按钮;富内容用 slot="header",插槽优先) | string | — |
open | 展开态(受控开关):属性缺席 = 非受控自管(首帧由 default-open 播种);属性在场 = 受控(值非 "false" 为展开、"false" 为收起),点击翻转后写回属性并派发事件(乐观更新) | — | — |
事件
| 事件 | 说明 |
|---|---|
oas-toggle | 开合状态变化后派发,detail { open }(受控与非受控模式均派发) |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 折叠体内容 |
header | 触发器富内容插槽,覆盖 header 属性文案 |
template[slot="toggle"] | 自定义展开图标模板(缺省为内建箭头) |