Skip to content

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"]自定义展开图标模板(缺省为内建箭头)

基于 MIT OR Apache-2.0 双许可发布