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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "24 · 列表 List",
  "confidence": "high",
  "slug": "mobile-list",
  "name": "列表 List",
  "semanticTypeCandidates": [
    "list",
    "list-group",
    "settings-list"
  ],
  "variantDimensions": [
    {
      "name": "border",
      "values": [
        "true",
        "false"
      ]
    },
    {
      "name": "size",
      "values": [
        "default",
        "compact"
      ]
    },
    {
      "name": "divider",
      "values": [
        "inset",
        "full"
      ]
    }
  ],
  "representativeVariants": [
    {
      "border": "true",
      "size": "default",
      "divider": "inset",
      "label": "标准分组列表（默认：行高 56px、分隔线缩进）"
    },
    {
      "border": "true",
      "size": "compact",
      "divider": "full",
      "label": "紧凑高密度列表（行高 44px、通栏分隔线）"
    },
    {
      "border": "false",
      "size": "default",
      "divider": "inset",
      "label": "无分隔线列表（靠留白分组）"
    }
  ],
  "anatomy": {
    "list": "根元素，一个列表区块",
    "header": "可选分组标题，位于列表之上",
    "item": "列表项，一行承载「前缀 + 主区 + 后缀」",
    "prefix": "可选前缀位（头像、图标、序号）",
    "body": "主区，标题 + 可选副标题，两行都单行省略",
    "suffix": "可选后缀位（值文字、标签、箭头、开关）",
    "footer": "可选分组脚注，用于补充说明"
  },
  "structurePatterns": {
    "border": "true（行间 1px 分隔线）/ false（无分隔线，靠间距分组）",
    "size": "default（行高 56px）/ compact（行高 44px）",
    "divider": "inset（分隔线缩进到行内容起点）/ full（通栏分隔线）"
  },
  "usageHints": [
    "把一组同类信息按行排列，用于「设置项 / 订单 / 成员」这类需要扫读的场合",
    "移动端一屏只有 6~8 行，每行信息层级必须收敛到「标题 + 可选的说明或值」",
    "分组之间用标题与留白分隔，而不是靠边框",
    "可点行整行都是热区，default 行高不小于 56px、compact 不小于 44px",
    "列表滚动由宿主容器负责；本组件不接管滚动、不做虚拟列表"
  ],
  "doNotInvent": [
    "虚拟滚动与无限加载的触发规则",
    "行的拖拽排序与左滑操作（那是 SwipeCell 的职责）"
  ],
  "unknowns": [
    "单行最多几列（前缀 + 主区 + 后缀之外的排布）",
    "分组标题是否吸顶"
  ],
  "interaction": [
    "可点行整行都是热区，default 行高不小于 56px、compact 不小于 44px",
    "按下反馈是整行背景变化，不是只有文字变色",
    "前缀位不参与点击判定（点图标等于点整行），后缀位里的独立控件（开关、按钮）要阻止事件冒泡，避免一次点击触发两个动作",
    "列表滚动由宿主容器负责；本组件不接管滚动、不做虚拟列表"
  ],
  "accessibility": [
    "容器 role=\"list\"，纯展示行 role=\"listitem\"；可点行用原生 button（原生语义优先于 listitem）",
    "分组标题用 aria-label 或可见文本，读屏在进入分组时能读到",
    "空列表用 aria-live=\"polite\" 播报占位文案"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "items",
        "type": "Array",
        "default": "[]",
        "desc": "数据驱动的行数组，每项含 title / desc / value / prefix / arrow / static / disabled（规格 §24.2）",
        "required": false
      },
      {
        "name": "size",
        "type": "'default' | 'compact'",
        "default": "'default'",
        "desc": "变体 size：default 行高 56px / compact 44px（规格 §24.3）",
        "required": false
      },
      {
        "name": "border",
        "type": "boolean",
        "default": "true",
        "desc": "变体 border：是否画行间 1px 分隔线（规格 §24.3）",
        "required": false
      },
      {
        "name": "divider",
        "type": "'inset' | 'full'",
        "default": "'inset'",
        "desc": "变体 divider：分隔线缩进到内容起点 / 通栏（规格 §24.3）",
        "required": false
      },
      {
        "name": "header",
        "type": "string",
        "default": "''",
        "desc": "分组标题，位于列表之上（规格 §24.2 header）",
        "required": false
      },
      {
        "name": "footer",
        "type": "string",
        "default": "''",
        "desc": "分组脚注，用于补充说明（规格 §24.2 footer）",
        "required": false
      },
      {
        "name": "emptyText",
        "type": "string",
        "default": "''",
        "desc": "状态 empty：列表为空时的占位文案（规格 §24.4）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "select",
        "params": "(index)",
        "desc": "可点行被点击时触发，回传该行在 items 里的下标"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "追加在数据驱动行之后的自定义行（规格 §24.2 item）"
      },
      {
        "name": "empty",
        "desc": "状态 empty 的自定义占位内容，替代 emptyText（规格 §24.4）"
      }
    ]
  },
  "variantClasses": {
    "border": {
      "true": [
        ".kole-m-list--border"
      ],
      "false": []
    },
    "size": {
      "default": [],
      "compact": [
        ".kole-m-list--compact"
      ]
    },
    "divider": {
      "inset": [
        ".kole-m-list--inset"
      ],
      "full": [
        ".kole-m-list--full"
      ]
    }
  },
  "demos": [
    {
      "id": "basic",
      "group": "01 组件类型",
      "title": "基础列表",
      "desc": "标题 + 副标题 + 后缀位（值 + 箭头），行间 1px 分隔线且最后一条不画。",
      "variant": "border=true / divider=inset"
    },
    {
      "id": "prefix",
      "group": "01 组件类型",
      "title": "带前缀位",
      "desc": "前缀放头像、图标或序号；它是装饰，点击等于点整行。",
      "variant": "anatomy.prefix"
    },
    {
      "id": "custom",
      "group": "01 组件类型",
      "title": "自定义后缀",
      "desc": "后缀位放标签这类非文字内容，与值文字共用一行。",
      "variant": "anatomy.suffix"
    },
    {
      "id": "divider",
      "group": "01 组件类型",
      "title": "分隔线两态",
      "desc": "divider=inset 时线从行内容起点开始；divider=full 时通栏不缩进。",
      "variant": "divider=inset|full"
    },
    {
      "id": "compact",
      "group": "02 组件状态",
      "title": "紧凑尺寸",
      "desc": "size=compact 行高 44px，仍是触控最小边长，用于高密度筛选类列表。",
      "variant": "size=compact"
    },
    {
      "id": "clickable",
      "group": "02 组件状态",
      "title": "可点行",
      "desc": "可点行是原生 button：键盘可达、按下整行背景变化。",
      "variant": "events.select"
    },
    {
      "id": "disabled",
      "group": "02 组件状态",
      "title": "禁用行",
      "desc": "状态 disabled：置灰且不响应点击，用于无权限项。",
      "variant": "状态 disabled"
    },
    {
      "id": "empty",
      "group": "02 组件状态",
      "title": "空列表",
      "desc": "状态 empty：占位文案用 aria-live 播报，读屏能听到「暂无订单」。",
      "variant": "状态 empty"
    }
  ],
  "related": [
    {
      "slug": "cell",
      "why": "单行信息用单元格（自带 arrow / value 语义）；成组出现且需要分组标题与脚注时用列表"
    },
    {
      "slug": "swipecell",
      "why": "行内还需要左滑操作时用滑动单元格；只做扫读与点击用列表"
    },
    {
      "slug": "mobile-avatar",
      "why": "行的前缀位放头像时用头像组件；列表只负责行的骨架"
    },
    {
      "slug": "mobile-collapse",
      "why": "行点击后要就地展开内容用折叠面板；跳转到新页面用列表的可点行"
    }
  ]
}