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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "22 · 加载 Loading",
  "confidence": "high",
  "slug": "mobile-loading",
  "name": "加载 Loading",
  "semanticTypeCandidates": [
    "loading",
    "spinner"
  ],
  "variantDimensions": [
    {
      "name": "size",
      "values": [
        "small",
        "default",
        "large"
      ]
    },
    {
      "name": "vertical",
      "values": [
        "false",
        "true"
      ]
    },
    {
      "name": "fullscreen",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "size": "default",
      "vertical": "false",
      "label": "区块内加载（转圈 + 文案同行）"
    },
    {
      "size": "small",
      "vertical": "false",
      "label": "列表内联加载"
    },
    {
      "size": "large",
      "vertical": "true",
      "label": "空态 / 页面级加载（上下排布）"
    },
    {
      "size": "default",
      "fullscreen": "true",
      "label": "全屏遮罩（不可中断的提交）"
    }
  ],
  "anatomy": {
    "loading": "根元素，内联形态（转圈 + 文案同行或上下排）；fullscreen=true 时它本身即遮罩层",
    "spinner": "转圈，由 CSS 动画驱动（三端一致，不依赖图片或字体）",
    "text": "可选文案，说明「在等什么」；为空时只有转圈",
    "panel": "全屏形态下的卡片面板，承载指示器与文案，保证遮罩上的对比度可控",
    "mask": "全屏形态的遮罩底色（取令牌，语义等同弹窗遮罩）"
  },
  "structurePatterns": {
    "size": "small 16px / default 20px / large 28px",
    "vertical": "false 横行（默认）/ true 上下排布",
    "fullscreen": "false 区块内 / true 遮罩全屏（open 控制显隐）"
  },
  "usageHints": [
    "告诉用户「系统正在处理，请等」并占住当前位置",
    "加载组件本身不可点，也不抢焦点（不打断读屏正在读的内容）",
    "fullscreen=true 且 open 时遮罩截获手势，下方内容不可点；未展开时不截获",
    "转圈动画 800ms/圈（--kole-m-loading-duration 可覆盖），时长恒定不随尺寸变化",
    "prefers-reduced-motion: reduce 下停止旋转（改为静态环），避免前庭不适"
  ],
  "doNotInvent": [
    "加载耗时的进度百分比（本组件不假装知道进度）",
    "超时后的自动提示 / 自动重试",
    "多条加载的排队与合并"
  ],
  "unknowns": [
    "全屏加载持续多久后应提示「可能需要更长时间」",
    "文案的最大长度与换行策略"
  ],
  "interaction": [
    "加载组件本身不可点，也不抢焦点（不打断读屏正在读的内容）",
    "fullscreen=true 且 open 时遮罩截获手势，下方内容不可点；未展开时不截获",
    "转圈动画 800ms/圈（--kole-m-loading-duration 可覆盖），时长恒定不随尺寸变化",
    "prefers-reduced-motion: reduce 下停止旋转（改为静态环），避免前庭不适",
    "加载超过一次会话的合理时长时应由宿主提供取消入口，本组件不自己造取消按钮"
  ],
  "accessibility": [
    "容器 role=\"status\" + aria-live=\"polite\"（状态变化被播报，且不打断当前朗读）",
    "加载中置 aria-busy=\"true\"；全屏遮罩未展开时置 \"false\"",
    "转圈是装饰（aria-hidden=\"true\"），语义全部由文案与 role=\"status\" 承担",
    "文案要具体（「正在提交订单…」而不是「加载中」），读屏用户与视力用户获得同样的信息量"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "size",
        "type": "'small' | 'default' | 'large'",
        "default": "'default'",
        "desc": "变体 size：三档指示器尺寸（16 / 20 / 28），文案字号随档位（规格 §22.3）",
        "required": false
      },
      {
        "name": "text",
        "type": "string",
        "default": "''",
        "desc": "文案，说明「在等什么」；为空时只有转圈（规格 §22.2）",
        "required": false
      },
      {
        "name": "vertical",
        "type": "boolean",
        "default": "false",
        "desc": "变体 vertical：true 时指示器在上、文案在下（规格 §22.3）",
        "required": false
      },
      {
        "name": "fullscreen",
        "type": "boolean",
        "default": "false",
        "desc": "变体 fullscreen：true 时铺一层遮罩并截获手势（规格 §22.3/§22.5）",
        "required": false
      },
      {
        "name": "open",
        "type": "boolean",
        "default": "false",
        "desc": "全屏遮罩的显隐；仅 fullscreen=true 时有意义（规格 §22.4）",
        "required": false
      }
    ],
    "events": [],
    "slots": [
      {
        "name": "default",
        "desc": "自定义文案（与 text 二选一）（规格 §22.2 text）"
      }
    ]
  },
  "variantClasses": {
    "size": {
      "small": [
        ".kole-m-loading--small"
      ],
      "default": [
        "--kole-m-loading-size"
      ],
      "large": [
        ".kole-m-loading--large"
      ]
    },
    "vertical": {
      "false": [],
      "true": [
        ".kole-m-loading--vertical"
      ]
    },
    "fullscreen": {
      "false": [],
      "true": [
        ".is-fullscreen",
        ".kole-m-loading__panel"
      ]
    }
  },
  "demos": [
    {
      "id": "basic",
      "group": "01 组件类型",
      "title": "基础用法",
      "desc": "转圈 + 文案同行；文案要说明「在等什么」，只写「加载中」等于没说。",
      "variant": "size=default / vertical=false"
    },
    {
      "id": "size",
      "group": "01 组件类型",
      "title": "三档尺寸",
      "desc": "small 用于列表内联，default 用于区块，large 用于页面级或空态。",
      "variant": "size=small | default | large"
    },
    {
      "id": "vertical",
      "group": "01 组件类型",
      "title": "上下排布",
      "desc": "vertical=true 让文案不挤压指示器，空态与全屏面板里更稳。",
      "variant": "vertical=true"
    },
    {
      "id": "text-only",
      "group": "02 组件状态",
      "title": "无文案",
      "desc": "只有转圈时，上下文说明必须由宿主在别处给出，否则用户不知道在等什么。",
      "variant": "text=''"
    },
    {
      "id": "fullscreen",
      "group": "02 组件状态",
      "title": "全屏遮罩",
      "desc": "遮罩期间下方不可操作，用来挡住提交 / 支付这类动作的重复点击（点按钮切换）。",
      "variant": "fullscreen=true / open"
    }
  ],
  "related": [
    {
      "slug": "mobile-toast",
      "why": "只提示结果（成功 / 失败）且不要求等待时用轻提示；需要用户等待才用加载"
    },
    {
      "slug": "mobile-dialog",
      "why": "需要用户先确认才能继续时用对话框；加载不征求用户意见"
    },
    {
      "slug": "pullrefresh",
      "why": "列表顶部下拉触发的刷新用它（自带手势与指示区）；区块内的等待才用加载"
    },
    {
      "slug": "mobile-icon",
      "why": "只需要一个静态字形（不是等待语义）时用图标，不要拿图标假装加载"
    }
  ]
}