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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "20 · 布局 Layout",
  "confidence": "high",
  "slug": "mobile-layout",
  "name": "布局 Layout",
  "semanticTypeCandidates": [
    "layout",
    "grid"
  ],
  "variantDimensions": [
    {
      "name": "gutter",
      "values": [
        "0",
        "8",
        "16",
        "24"
      ]
    },
    {
      "name": "columns",
      "values": [
        "0",
        "2",
        "3",
        "4"
      ]
    },
    {
      "name": "align",
      "values": [
        "start",
        "center",
        "end",
        "stretch"
      ]
    },
    {
      "name": "wrap",
      "values": [
        "true",
        "false"
      ]
    }
  ],
  "representativeVariants": [
    {
      "columns": "2",
      "gutter": "8",
      "label": "两等分（左右对照）"
    },
    {
      "columns": "3",
      "gutter": "16",
      "label": "三等分（短字段）"
    },
    {
      "columns": "4",
      "gutter": "8",
      "label": "四等分（指标卡 / 入口）"
    },
    {
      "columns": "0",
      "gutter": "16",
      "label": "不等宽（列级 span 主次分栏）"
    }
  ],
  "anatomy": {
    "layout": "行容器，display: flex + 换行，承载列间距变量",
    "col": "列，默认占满一行（flex-basis: 100%），由行级等分或列级 span 类决定实际宽度",
    "panel": "列内容的可选包壳，提供内边距与最小高度，业务也可直接放自己的卡片",
    "gutter": "列间距，四档（0 / 8 / 16 / 24），由行级类写到 CSS 变量上",
    "span": "列级权重类（12 栅格取值），可覆盖行级等分"
  },
  "structurePatterns": {
    "gutter": "0 无缝 / 8 紧凑 / 16 常规 / 24 宽松，由 --kole-m-layout-gutter 承载",
    "columns": "0 不启用等分 / 2 / 3 / 4 等分（行级）",
    "align": "start / center / end / stretch（交叉轴）",
    "wrap": "true 换行（默认）/ false 横向滚动"
  },
  "usageHints": [
    "把一行内容按比例切成若干列（等分或按 12 栅格取值）",
    "布局容器不绑点击，不设 cursor: pointer，热区始终由列内的业务元素提供",
    "列内若是可点区域，其热区不小于 44×44（见 §19.5 与 §6.5）",
    "gutter 由 CSS 变量承载，同一行内所有列的宽度计算共用该变量，避免手工算宽",
    "列宽使用 flex-basis: calc(...)，窄屏下不产生横向溢出（列内文本默认 min-width: 0）"
  ],
  "doNotInvent": [
    "响应式断点（移动端只有一档列数，不为大屏定义断点）",
    "列的排序 / 拖拽",
    "栅格嵌套的层级规则"
  ],
  "unknowns": [
    "列内推荐的最大列数（本实现提供 2 / 3 / 4 三档）",
    "列高等分（stretch 之外的等高策略）"
  ],
  "interaction": [
    "布局容器不绑点击，不设 cursor: pointer，热区始终由列内的业务元素提供",
    "列内若是可点区域，其热区不小于 44×44（见 §19.5 与 §6.5）",
    "gutter 由 CSS 变量承载，同一行内所有列的宽度计算共用该变量，避免手工算宽",
    "wrap=false 时容器横向滚动，纵向页面滚动不受影响"
  ],
  "accessibility": [
    "布局是纯视觉分组：不添加 role、不添加 aria-*",
    "不要为了布局把语义节点（列表 / 按钮）拆到不相邻的列里，否则读屏顺序会错乱",
    "视觉顺序必须与 DOM 顺序一致（不用 order 重排）"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "gutter",
        "type": "0 | 8 | 16 | 24",
        "default": "8",
        "desc": "变体 gutter：列间距四档，由 CSS 变量承载（规格 §20.3）",
        "required": false
      },
      {
        "name": "columns",
        "type": "0 | 2 | 3 | 4",
        "default": "0",
        "desc": "变体 columns：行级等分列数，0 表示不启用等分（规格 §20.3）",
        "required": false
      },
      {
        "name": "align",
        "type": "'start' | 'center' | 'end' | 'stretch'",
        "default": "'start'",
        "desc": "变体 align：交叉轴对齐（规格 §20.3）",
        "required": false
      },
      {
        "name": "wrap",
        "type": "boolean",
        "default": "true",
        "desc": "变体 wrap：false 时不换行、横向滚动（规格 §20.3）",
        "required": false
      }
    ],
    "events": [],
    "slots": [
      {
        "name": "default",
        "desc": "列（.kole-m-layout__col）或任意业务内容（规格 §20.2）"
      }
    ]
  },
  "variantClasses": {
    "gutter": {
      "0": [
        ".kole-m-layout--gutter-0"
      ],
      "8": [
        ".kole-m-layout--gutter-8",
        "--kole-m-layout-gutter"
      ],
      "16": [
        ".kole-m-layout--gutter-16"
      ],
      "24": [
        ".kole-m-layout--gutter-24"
      ]
    },
    "columns": {
      "0": [],
      "2": [
        ".kole-m-layout--cols-2"
      ],
      "3": [
        ".kole-m-layout--cols-3"
      ],
      "4": [
        ".kole-m-layout--cols-4"
      ]
    },
    "align": {
      "start": [],
      "center": [
        ".kole-m-layout--align-center"
      ],
      "end": [
        ".kole-m-layout--align-end"
      ],
      "stretch": [
        ".kole-m-layout--align-stretch"
      ]
    },
    "wrap": {
      "true": [],
      "false": [
        ".is-nowrap"
      ]
    }
  },
  "demos": [
    {
      "id": "cols-2",
      "group": "01 组件类型",
      "title": "两等分",
      "desc": "左右对照型信息（待付款 / 待发货）用两等分，列宽自动均分不手算。",
      "variant": "columns=2 / gutter=8"
    },
    {
      "id": "cols-3",
      "group": "01 组件类型",
      "title": "三等分",
      "desc": "金额、数量、优惠这类短字段用三等分；列内文字过长会换行而不是撑破列宽。",
      "variant": "columns=3 / gutter=16"
    },
    {
      "id": "cols-4",
      "group": "01 组件类型",
      "title": "四等分",
      "desc": "指标卡与图标入口最常用的档位；窄屏下保持四列，不折行。",
      "variant": "columns=4 / gutter=8"
    },
    {
      "id": "gutter",
      "group": "02 组件状态",
      "title": "列间距",
      "desc": "0 无缝只用于靠分割线或底色分栏的场景；常规内容用 8 或 16。",
      "variant": "gutter=0 | 24"
    },
    {
      "id": "span",
      "group": "02 组件状态",
      "title": "不等宽",
      "desc": "主次分栏用列级 span 覆盖行级等分：主栏 8/12，次栏 4/12。",
      "variant": "col--8 + col--4"
    },
    {
      "id": "align",
      "group": "02 组件状态",
      "title": "交叉轴对齐",
      "desc": "列高不同时用 align=center 让内容垂直居中，默认 start 顶部对齐。",
      "variant": "align=center"
    },
    {
      "id": "nowrap",
      "group": "02 组件状态",
      "title": "不换行",
      "desc": "wrap=false 时列横向滚动，纵向页面滚动不受影响（看板式横向列）。",
      "variant": "wrap=false"
    }
  ],
  "related": [
    {
      "slug": "mobile-grid",
      "why": "等分的图标 / 文字入口用宫格（自带图标与文字样式）；只是切分版面才用布局"
    },
    {
      "slug": "mobile-divider",
      "why": "列之间要靠线分栏时用分割线；布局只管间距与宽度"
    },
    {
      "slug": "cell",
      "why": "一行一个语义项（可点整行）用单元格；一行要放多个并列块才用布局"
    }
  ]
}