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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "confidence": "high",
  "specSection": "14 · 宫格 Grid",
  "slug": "mobile-grid",
  "name": "宫格 Grid",
  "semanticTypeCandidates": [
    "grid",
    "menu",
    "shortcut"
  ],
  "variantDimensions": [
    {
      "name": "columns",
      "values": [
        "2",
        "3",
        "4"
      ]
    },
    {
      "name": "border",
      "values": [
        "false",
        "true"
      ]
    },
    {
      "name": "square",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "columns": "4",
      "border": "false",
      "square": "false",
      "label": "四列宫格（最常用）"
    },
    {
      "columns": "3",
      "border": "false",
      "square": "false",
      "label": "三列宫格"
    },
    {
      "columns": "2",
      "border": "false",
      "square": "true",
      "label": "两列正方形"
    },
    {
      "columns": "4",
      "border": "true",
      "square": "false",
      "label": "带格线"
    }
  ],
  "anatomy": {
    "grid": "根容器",
    "grid__item": "单个格子（图标 + 文字）",
    "grid__icon": "图标区",
    "grid__text": "文字标签"
  },
  "structurePatterns": {
    "columns": "2 / 3 / 4（每行格数）",
    "border": "false / true（是否画格线）",
    "square": "false / true（格子是否为正方形）"
  },
  "usageHints": [
    "把图标 / 文字入口按等分列排成网格，用于首页功能入口区",
    "每个格子整块可点，热区不小于 44×44",
    "按下反馈用 :active（不用 :hover —— 触屏没有悬停）",
    "可点格子用原生 button（整块热区 + 键盘可达）",
    "纯展示格子用 div 且不加交互角色",
    "图标装饰（aria-hidden=\"true\"），文字即语义"
  ],
  "doNotInvent": [
    "格子的拖拽排序",
    "超出 4 列的响应式折行列数"
  ],
  "unknowns": [
    "图标区的推荐尺寸",
    "一格最多几个字"
  ],
  "interaction": [
    "每个格子整块可点，热区不小于 44×44",
    "按下反馈用 :active（不用 :hover —— 触屏没有悬停）"
  ],
  "accessibility": [
    "可点格子用原生 button（整块热区 + 键盘可达）",
    "纯展示格子用 div 且不加交互角色",
    "图标装饰（aria-hidden=\"true\"），文字即语义"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "columns",
        "type": "number",
        "default": "4",
        "desc": "变体 columns：每行格数（规格 §14.3）",
        "required": false
      },
      {
        "name": "border",
        "type": "boolean",
        "default": "false",
        "desc": "变体 border：是否画格线（规格 §14.3）",
        "required": false
      },
      {
        "name": "square",
        "type": "boolean",
        "default": "false",
        "desc": "变体 square：格子是否撑成正方形（规格 §14.3）",
        "required": false
      },
      {
        "name": "items",
        "type": "Array<{ text, icon, disabled, static }>",
        "default": "[]",
        "desc": "格子数据；static=true 的格子是纯展示（不绑点击）（规格 §14.2）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "select",
        "params": "index: number",
        "desc": "点击可点格子时触发，回传格子下标；跳转由宿主决定（规格 §14.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "额外的自定义格子（追加在 items 之后）"
      }
    ]
  },
  "variantClasses": {
    "columns": {
      "2": [
        ".kole-m-grid--2"
      ],
      "3": [
        ".kole-m-grid--3"
      ],
      "4": [
        ".kole-m-grid--4"
      ]
    },
    "border": {
      "false": [],
      "true": [
        ".kole-m-grid--border"
      ]
    },
    "square": {
      "false": [],
      "true": [
        ".kole-m-grid--square"
      ]
    }
  },
  "demos": [
    {
      "id": "columns-4",
      "group": "01 组件类型",
      "title": "四列宫格",
      "desc": "最常用的首页入口排布；每格是原生按钮，整块可点、键盘可达。",
      "variant": "columns=4"
    },
    {
      "id": "columns-3",
      "group": "01 组件类型",
      "title": "三列宫格",
      "desc": "每格更宽，适合带较长标题的入口。",
      "variant": "columns=3"
    },
    {
      "id": "columns-2",
      "group": "01 组件类型",
      "title": "两列正方形",
      "desc": "入口更少、信息更重时用；square=true 把格子撑成正方形，视觉更稳。",
      "variant": "columns=2 · square=true"
    },
    {
      "id": "border",
      "group": "02 组件状态",
      "title": "带格线",
      "desc": "格线用 outline 绘制，相邻边不会叠成 2px；适合需要明确分区边界的场景。",
      "variant": "border=true"
    },
    {
      "id": "disabled",
      "group": "02 组件状态",
      "title": "含禁用项",
      "desc": "禁用项置灰且不响应点击，多用于无权限入口；纯展示格子不绑任何交互。",
      "variant": "状态 disabled"
    }
  ],
  "related": [
    {
      "slug": "cell",
      "why": "一列一条的入口用单元格，2 列以上的入口才用宫格"
    },
    {
      "slug": "mobile-tag",
      "why": "格子上的状态标记用标签，不要把状态写进格子的标题文字里"
    },
    {
      "slug": "mobile-noticebar",
      "why": "宫格上方需要一条公告时用通知栏，不要在宫格里插说明文字"
    }
  ]
}