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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "5 · 滑动单元格 SwipeCell",
  "confidence": "high",
  "slug": "swipecell",
  "name": "滑动单元格 SwipeCell",
  "semanticTypeCandidates": [
    "swipe-cell",
    "list-item",
    "gesture"
  ],
  "variantDimensions": [
    {
      "name": "direction",
      "values": [
        "left",
        "right"
      ]
    },
    {
      "name": "actions",
      "values": [
        "1",
        "2"
      ]
    }
  ],
  "representativeVariants": [
    {
      "direction": "left",
      "actions": "1",
      "label": "左滑 · 单个操作"
    },
    {
      "direction": "left",
      "actions": "2",
      "label": "左滑 · 两个操作"
    },
    {
      "direction": "right",
      "actions": "1",
      "label": "右滑 · 单个操作"
    },
    {
      "direction": "left",
      "actions": "2",
      "label": "已展开态"
    }
  ],
  "anatomy": {
    "cell": "可滑动的行容器",
    "content": "行内容（标题、描述）",
    "actions": "右侧操作区，随滑动露出",
    "action": "单个操作按钮，可标记危险"
  },
  "structurePatterns": {
    "direction": "left（左滑露出右侧操作，默认）/ right（右滑露出左侧操作）",
    "actions": "1 / 2（操作数量，最多 2 个）"
  },
  "usageHints": [
    "列表行左滑露出操作按钮，用于删除、标记等单行操作",
    "横向位移超过 10px 判定为滑动，纵向位移更大时取消滑动",
    "松手后按位移是否超过操作区宽度的一半决定展开或回弹",
    "展开状态下点击内容区先收起，不触发内容点击",
    "操作按钮为原生 button，具备 aria-label",
    "滑动不可作为唯一路径：操作按钮在展开后必须可键盘聚焦"
  ],
  "doNotInvent": [
    "多行同时展开的互斥规则",
    "滑动与纵向滚动的竞争阈值细节"
  ],
  "unknowns": [
    "操作区宽度是否有标准档位",
    "拖拽中的阴影表现"
  ],
  "interaction": [
    "横向位移超过 10px 判定为滑动，纵向位移更大时取消滑动",
    "松手后按位移是否超过操作区宽度的一半决定展开或回弹",
    "展开状态下点击内容区先收起，不触发内容点击"
  ],
  "accessibility": [
    "操作按钮为原生 button，具备 aria-label",
    "滑动不可作为唯一路径：操作按钮在展开后必须可键盘聚焦"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "props": [
      {
        "name": "direction",
        "type": "'left' | 'right'",
        "default": "'left'",
        "desc": "变体 direction：左滑露出右侧操作或右滑露出左侧操作（规格 §5.3）",
        "required": false
      },
      {
        "name": "actions",
        "type": "Action[]",
        "default": "[]",
        "desc": "操作项（最多 2 个）：{ key, label, tone?, ariaLabel? }（规格 §5.2/§5.3）",
        "required": false
      },
      {
        "name": "open",
        "type": "boolean",
        "default": "false",
        "desc": "受控展开态（closed / open，规格 §5.4）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "action",
        "params": "key, action",
        "desc": "点击某个操作按钮时触发"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "行内容（标题、描述；规格 §5.2）"
      }
    ],
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。"
  },
  "variantClasses": {
    "direction": {
      "left": [],
      "right": [
        ".kole-m-swipecell--right"
      ]
    },
    "actions": {
      "1": [
        ".kole-m-swipecell__action"
      ],
      "2": [
        ".kole-m-swipecell__action"
      ]
    }
  },
  "demos": [
    {
      "id": "left-single",
      "group": "01 组件类型",
      "title": "左滑 · 单个操作",
      "desc": "最常用的形态：左滑露出一个操作；位移超过操作区一半即展开。",
      "variant": "direction=left / actions=1"
    },
    {
      "id": "left-double",
      "group": "01 组件类型",
      "title": "左滑 · 两个操作",
      "desc": "两个操作为上限；破坏性操作放最右（拇指行程最短，也最不易误触）。",
      "variant": "actions=2"
    },
    {
      "id": "right-single",
      "group": "01 组件类型",
      "title": "右滑 · 单个操作",
      "desc": "右滑露出左侧操作，适合「标记已读」这类非破坏性动作。",
      "variant": "direction=right"
    },
    {
      "id": "open",
      "group": "02 组件状态",
      "title": "已展开态",
      "desc": "展开后操作按钮可键盘聚焦 —— 滑动不是唯一路径（无障碍要求）。",
      "variant": "open=true"
    }
  ],
  "related": [
    {
      "slug": "actionsheet",
      "why": "需要标题与统一取消的批量选择用动作面板；行内单点操作用滑动单元格"
    },
    {
      "slug": "tabbar",
      "why": "长列表底部常带标签栏，滑动时要保证列表可滚、标签栏不动"
    }
  ]
}