{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "26 · 进度条 Progress",
  "confidence": "high",
  "slug": "mobile-progress",
  "name": "进度条 Progress",
  "semanticTypeCandidates": [
    "progress",
    "progress-bar",
    "progress-ring"
  ],
  "variantDimensions": [
    {
      "name": "type",
      "values": [
        "line",
        "circle"
      ]
    },
    {
      "name": "status",
      "values": [
        "normal",
        "success",
        "error"
      ]
    },
    {
      "name": "labelPlacement",
      "values": [
        "inside",
        "right",
        "center"
      ]
    }
  ],
  "representativeVariants": [
    {
      "type": "line",
      "status": "normal",
      "labelPlacement": "right",
      "label": "线形进行中（文案在条右侧）"
    },
    {
      "type": "line",
      "status": "success",
      "labelPlacement": "inside",
      "label": "线形成功（文案压在条内）"
    },
    {
      "type": "circle",
      "status": "normal",
      "labelPlacement": "center",
      "label": "环形进行中（文案在环心）"
    },
    {
      "type": "line",
      "status": "error",
      "labelPlacement": "right",
      "label": "线形失败（进度停在断点转错误色）"
    }
  ],
  "anatomy": {
    "progress": "根元素，承载轨道与文案",
    "track": "轨道，未完成部分的底色",
    "bar": "已完成部分，宽度由 percentage 决定",
    "ring": "环形进度的圆环轨道（type=circle 时替代 track/bar）",
    "label": "百分比文案，可置于条内、条右侧或环心",
    "status": "状态图标位（成功 / 失败），非进行中时显示"
  },
  "structurePatterns": {
    "type": "line（线形）/ circle（环形）",
    "status": "normal（进行中，品牌色）/ success（成功）/ error（失败）",
    "labelPlacement": "inside（文案在条内）/ right（条右侧）/ center（环心，仅 circle）"
  },
  "usageHints": [
    "把一个过程的完成度可视化（上传、审核、额度耗尽）",
    "移动端的进度多数伴随文字出现，因此百分比文案与状态色是标配而非可选",
    "进度变化要能被读屏播报而不只是画出来",
    "进度条本身不可交互、不接收点击；需要取消时由宿主在旁边放按钮",
    "数值变化用 CSS 宽度过渡（240ms），不做无限循环动画（省电且不干扰读屏）"
  ],
  "doNotInvent": [
    "环形进度的线宽与半径的自适应规则（由 size 决定，不做响应式推导）",
    "进度到达 100% 后的自动隐藏时机"
  ],
  "unknowns": [
    "百分比是否四舍五入到整数",
    "环形进度是否支持渐变描边"
  ],
  "interaction": [
    "进度条本身不可交互、不接收点击；需要取消时由宿主在旁边放按钮",
    "数值变化用 CSS 宽度过渡（240ms），不做无限循环动画（省电且不干扰读屏）",
    "无动画偏好（prefers-reduced-motion）下直接跳到目标宽度"
  ],
  "accessibility": [
    "根节点 role=\"progressbar\" + aria-valuemin=\"0\" / aria-valuemax=\"100\" / aria-valuenow",
    "文案节点 aria-hidden=\"true\"，避免与 aria-valuenow 重复播报",
    "不确定进度（无法给出百分比）用 aria-valuetext=\"进行中\" 表达"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "percentage",
        "type": "number",
        "default": "0",
        "desc": "完成度 0~100，超出范围按边界收敛（规格 §26.2 bar）",
        "required": false
      },
      {
        "name": "type",
        "type": "'line' | 'circle'",
        "default": "'line'",
        "desc": "变体 type：线形 / 环形（规格 §26.3）",
        "required": false
      },
      {
        "name": "status",
        "type": "'normal' | 'success' | 'error'",
        "default": "'normal'",
        "desc": "变体 status：进行中 / 成功 / 失败，决定条体色相（规格 §26.3）",
        "required": false
      },
      {
        "name": "labelPlacement",
        "type": "'inside' | 'right' | 'center'",
        "default": "'right'",
        "desc": "变体 labelPlacement：文案位置；center 仅对环形有效（规格 §26.3）",
        "required": false
      },
      {
        "name": "label",
        "type": "string",
        "default": "''",
        "desc": "自定义文案，缺省显示「percentage%」（规格 §26.2 label）",
        "required": false
      },
      {
        "name": "paused",
        "type": "boolean",
        "default": "false",
        "desc": "状态 paused：暂停，条体降透明度且进度保留（规格 §26.4）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "—",
        "params": "—",
        "desc": "无事件；进度条不可交互（规格 §26.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "追加在进度条之后的自定义内容（如「取消」按钮）（规格 §26.2 status）"
      }
    ]
  },
  "variantClasses": {
    "type": {
      "line": [
        ".kole-m-progress--line"
      ],
      "circle": [
        ".kole-m-progress--circle"
      ]
    },
    "status": {
      "normal": [],
      "success": [
        ".kole-m-progress--success"
      ],
      "error": [
        ".kole-m-progress--error"
      ]
    },
    "labelPlacement": {
      "inside": [
        ".kole-m-progress--inside"
      ],
      "right": [
        ".kole-m-progress--right"
      ],
      "center": [
        ".kole-m-progress__hole",
        "--kole-m-progress-percent"
      ]
    }
  },
  "demos": [
    {
      "id": "line",
      "group": "01 组件类型",
      "title": "线形",
      "desc": "type=line + labelPlacement=right：文案固定在条右侧，数字用等宽数字避免跳动。",
      "variant": "type=line / labelPlacement=right"
    },
    {
      "id": "inside",
      "group": "01 组件类型",
      "title": "文案在条内",
      "desc": "labelPlacement=inside 时条体加高到 20px 以容纳文字，适合窄屏与卡片内。",
      "variant": "labelPlacement=inside"
    },
    {
      "id": "status",
      "group": "02 组件状态",
      "title": "三种状态",
      "desc": "进行中 / 成功 / 失败：色相不同，且都带文案与状态图标，不靠颜色单独表意。",
      "variant": "status=normal|success|error"
    },
    {
      "id": "circle",
      "group": "01 组件类型",
      "title": "环形",
      "desc": "type=circle + labelPlacement=center：环心挖空与所在容器同底，文案在环心。",
      "variant": "type=circle / labelPlacement=center"
    },
    {
      "id": "paused",
      "group": "02 组件状态",
      "title": "暂停",
      "desc": "状态 paused：条体降透明度、进度保留，用户能看出「停住了」而不是「没开始」。",
      "variant": "paused=true"
    },
    {
      "id": "clickable",
      "group": "02 组件状态",
      "title": "进度不可交互",
      "desc": "进度条本身不接收点击；需要打断时由宿主在旁边放按钮（演示里用按钮把进度推到 100%）。",
      "variant": "无事件"
    }
  ],
  "related": [
    {
      "slug": "mobile-steps",
      "why": "过程有明确的阶段（提交 → 审核 → 完成）用步骤条；只有完成度没有阶段时用进度条"
    },
    {
      "slug": "pullrefresh",
      "why": "等待短任务完成用下拉刷新的加载态；长过程需要量化完成度时用进度条"
    },
    {
      "slug": "mobile-toast",
      "why": "过程瞬间完成只需一句轻提示；过程持续可见才需要进度条"
    }
  ]
}