aurora-admin/.design_library/kole-ui-mobile/components/mobile-collapse.json

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "25 · 折叠面板 Collapse",
  "confidence": "high",
  "slug": "mobile-collapse",
  "name": "折叠面板 Collapse",
  "semanticTypeCandidates": [
    "collapse",
    "accordion",
    "disclosure"
  ],
  "variantDimensions": [
    {
      "name": "accordion",
      "values": [
        "false",
        "true"
      ]
    },
    {
      "name": "bordered",
      "values": [
        "true",
        "false"
      ]
    }
  ],
  "representativeVariants": [
    {
      "accordion": "false",
      "bordered": "true",
      "label": "多面板带边框（默认：各自开合互不影响）"
    },
    {
      "accordion": "true",
      "bordered": "true",
      "label": "手风琴（同时只展开一个，移动端推荐形态）"
    },
    {
      "accordion": "false",
      "bordered": "false",
      "label": "无边框面板（靠留白分隔，适合嵌在卡片内）"
    }
  ],
  "anatomy": {
    "collapse": "根元素，一组面板的容器",
    "item": "单个面板，含标题行与内容区",
    "header": "标题行，整行可点，高度不小于 44px",
    "arrow": "标题行右侧箭头，展开时旋转 90 度",
    "panel": "内容区，展开时可见（收起时高度为 0 或 hidden）",
    "content": "内容区内的正文节点"
  },
  "structurePatterns": {
    "accordion": "false（多面板可同时展开）/ true（手风琴，同时只展开一个）",
    "bordered": "true（面板之间有分隔线与外框）/ false（无边框，靠留白分隔）"
  },
  "usageHints": [
    "把长内容按主题收起来，让用户先看到标题、按需展开某一段",
    "移动端屏幕窄，展开后内容会顶走上下文，因此一次只展开一个（手风琴）是默认推荐形态",
    "展开态必须明确到不靠颜色也能看出（箭头方向 + aria-expanded）",
    "标题行整行都是热区，高度不小于 44px",
    "手风琴模式下展开新面板会收起当前展开项；accordion=false 时互不影响"
  ],
  "doNotInvent": [
    "展开动画的高度换算公式（内容高度由浏览器决定）",
    "嵌套折叠面板的层级样式"
  ],
  "unknowns": [
    "默认是否展开第一项",
    "标题行右侧是否允许放额外操作"
  ],
  "interaction": [
    "标题行整行都是热区，高度不小于 44px",
    "视觉箭头转 90 度（180ms 过渡），展开时 aria-expanded 同步为 true",
    "手风琴模式下展开新面板会收起当前展开项；accordion=false 时互不影响",
    "内容区不做高度动画，直接切换 hidden（省电，读屏也不会读到中间态）；减少动态偏好下箭头同样瞬时切换"
  ],
  "accessibility": [
    "标题行用原生 button 并带 aria-expanded / aria-controls",
    "内容区与标题用 id / aria-controls 建立关联，收起时用 hidden 属性隐藏（而不是只靠 CSS 高度）",
    "禁用项置 aria-disabled=\"true\" 且不可聚焦"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "items",
        "type": "Array",
        "default": "[]",
        "desc": "数据驱动的面板数组，每项含 key / title / content / disabled（规格 §25.2）",
        "required": false
      },
      {
        "name": "accordion",
        "type": "boolean",
        "default": "false",
        "desc": "变体 accordion：手风琴模式，展开新面板时收起当前展开项（规格 §25.3）",
        "required": false
      },
      {
        "name": "bordered",
        "type": "boolean",
        "default": "true",
        "desc": "变体 bordered：面板之间有分隔线与外框（规格 §25.3）",
        "required": false
      },
      {
        "name": "value",
        "type": "Array",
        "default": "[]",
        "desc": "受控展开项：面板 key 的数组，点击后由 change 事件回传（规格 §25.5）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "change",
        "params": "(key, expanded)",
        "desc": "面板标题行被点击后触发，回传该面板 key 与展开态布尔值（规格 §25.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "追加在数据驱动面板之后的自定义面板（规格 §25.2 item）"
      }
    ]
  },
  "variantClasses": {
    "accordion": {
      "false": [],
      "true": [
        ".kole-m-collapse--accordion"
      ]
    },
    "bordered": {
      "true": [
        ".kole-m-collapse--bordered"
      ],
      "false": []
    }
  },
  "demos": [
    {
      "id": "basic",
      "group": "01 组件类型",
      "title": "基础用法",
      "desc": "点标题行展开：整行热区不小于 52px，箭头转 90 度，aria-expanded 同步变化。",
      "variant": "accordion=false"
    },
    {
      "id": "multi",
      "group": "01 组件类型",
      "title": "多面板同时展开",
      "desc": "accordion=false 时各面板各自开合，互不影响。",
      "variant": "accordion=false"
    },
    {
      "id": "accordion",
      "group": "01 组件类型",
      "title": "手风琴",
      "desc": "accordion=true 时展开新面板会自动收起当前展开项，适合主题多、屏幕窄的场合。",
      "variant": "accordion=true"
    },
    {
      "id": "bordered",
      "group": "02 组件状态",
      "title": "边框两态",
      "desc": "bordered=true 有外框与面板间分隔线；false 时靠留白分隔。",
      "variant": "bordered=true|false"
    },
    {
      "id": "disabled",
      "group": "02 组件状态",
      "title": "禁用面板",
      "desc": "状态 disabled：标题行置灰、不响应点击，aria-disabled 已置位且不可聚焦。",
      "variant": "状态 disabled"
    }
  ],
  "related": [
    {
      "slug": "mobile-list",
      "why": "行点击后跳转或选中用列表；就地展开内容用折叠面板"
    },
    {
      "slug": "mobile-popup",
      "why": "内容需要遮罩聚焦时用弹出层；内容属于当前上下文的补充说明时用折叠面板"
    },
    {
      "slug": "mobile-dialog",
      "why": "需要用户先决策再继续时用对话框；只是看说明用折叠面板"
    }
  ]
}