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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "23 · 头像 Avatar",
  "confidence": "high",
  "slug": "mobile-avatar",
  "name": "头像 Avatar",
  "semanticTypeCandidates": [
    "avatar",
    "user-image",
    "profile-photo"
  ],
  "variantDimensions": [
    {
      "name": "size",
      "values": [
        "small",
        "default",
        "large"
      ]
    },
    {
      "name": "shape",
      "values": [
        "circle",
        "square"
      ]
    },
    {
      "name": "type",
      "values": [
        "text",
        "image"
      ]
    }
  ],
  "representativeVariants": [
    {
      "size": "default",
      "shape": "circle",
      "type": "text",
      "label": "文字头像（圆形，用户默认形态）"
    },
    {
      "size": "large",
      "shape": "square",
      "type": "image",
      "label": "图片头像（圆角方形，企业 / 群组）"
    },
    {
      "size": "small",
      "shape": "circle",
      "type": "text",
      "label": "小尺寸头像（列表行前缀位）"
    },
    {
      "size": "default",
      "shape": "circle",
      "type": "image",
      "label": "图片加载失败退回文字（状态 fallback）"
    }
  ],
  "anatomy": {
    "avatar": "根元素，正方形圆角容器，尺寸由 size 决定",
    "image": "图片，铺满容器并按形状裁切",
    "text": "文字内容（姓名首字或简称），图片缺失时它就是主体",
    "fallback": "兜底节点，图片加载失败后退回的形状（文字或图标）",
    "badge": "可选右下角角标位，挂在线状态或未读数"
  },
  "structurePatterns": {
    "size": "small（32px）/ default（40px）/ large（56px）",
    "shape": "circle（圆形，用于人）/ square（圆角方形，用于企业或群组）",
    "type": "text（文字头像）/ image（图片头像，失败退文字）"
  },
  "usageHints": [
    "用一张图或一两个字符代表一个主体（用户、企业、群组）；移动端列表与详情页里大量出现，必须能单手扫读，因此尺寸只有三档、形状只有两种",
    "图片不可用时必须立刻退回文字，不能出现裂图",
    "头像本身不是按钮；可点时必须由宿主包一层原生 button 或 a，热区不小于 44×44",
    "图片 alt 或根节点 aria-label 必填其一，读屏读「姓名 + 头像」",
    "图片加载失败只触发一次 error 事件，是否替换资源由宿主决定"
  ],
  "doNotInvent": [
    "图片裁剪的 focal point（人脸居中）算法",
    "角标位置随形状（圆 / 方）的微调规则"
  ],
  "unknowns": [
    "文字头像的底色是否按名字散列取多色",
    "姓名超过两个汉字时的截断规则"
  ],
  "interaction": [
    "头像本身不是按钮；可点时必须由宿主包一层原生 button 或 a，热区不小于 44×44",
    "图片加载失败只触发一次 error 事件，是否替换资源由宿主决定"
  ],
  "accessibility": [
    "文字头像根节点 role=\"img\" 并带 aria-label（内容为姓名）",
    "图片头像直接用 <img alt>，alt 为空时视为装饰并对读屏隐藏",
    "角标不改变头像的可访问名"
  ],
  "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：三档尺寸 32 / 40 / 56px，文字随尺寸放大（规格 §23.3）",
        "required": false
      },
      {
        "name": "shape",
        "type": "'circle' | 'square'",
        "default": "'circle'",
        "desc": "变体 shape：circle 用于人，square 用于企业或群组（规格 §23.3）",
        "required": false
      },
      {
        "name": "type",
        "type": "'text' | 'image'",
        "default": "'text'",
        "desc": "变体 type：文字头像 / 图片头像，图片失败退回文字（规格 §23.3）",
        "required": false
      },
      {
        "name": "src",
        "type": "string",
        "default": "''",
        "desc": "图片地址，type=image 时必填（规格 §23.2 image）",
        "required": false
      },
      {
        "name": "alt",
        "type": "string",
        "default": "''",
        "desc": "可访问名：图片头像作为 <img alt>，文字头像作为根节点 aria-label（规格 §23.6）",
        "required": false
      },
      {
        "name": "disabled",
        "type": "boolean",
        "default": "false",
        "desc": "状态 disabled：置灰（如成员已离职）（规格 §23.4）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "error",
        "params": "(event)",
        "desc": "图片加载失败时触发一次；是否替换资源由宿主决定（规格 §23.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "文字内容（姓名首字或简称）（规格 §23.2 text）"
      },
      {
        "name": "badge",
        "desc": "右下角角标位，挂在线状态或未读数（规格 §23.2 badge）"
      }
    ]
  },
  "variantClasses": {
    "size": {
      "small": [
        ".kole-m-avatar--small"
      ],
      "default": [],
      "large": [
        ".kole-m-avatar--large"
      ]
    },
    "shape": {
      "circle": [
        ".kole-m-avatar--circle"
      ],
      "square": [
        ".kole-m-avatar--square"
      ]
    },
    "type": {
      "text": [],
      "image": [
        ".kole-m-avatar__image"
      ]
    }
  },
  "demos": [
    {
      "id": "size",
      "group": "01 组件类型",
      "title": "三档尺寸",
      "desc": "small 32 / default 40 / large 56，文字字号随尺寸放大，小尺寸下仍可读。",
      "variant": "size=small|default|large"
    },
    {
      "id": "shape",
      "group": "01 组件类型",
      "title": "两种形状",
      "desc": "circle 用于人（成员、好友），square 用于企业或群组（标志、团队）。",
      "variant": "shape=circle|square"
    },
    {
      "id": "image",
      "group": "01 组件类型",
      "title": "图片头像",
      "desc": "type=image 时图片铺满容器并按形状裁切，语义交给 <img alt>。",
      "variant": "type=image"
    },
    {
      "id": "fallback",
      "group": "02 组件状态",
      "title": "图片兜底",
      "desc": "状态 fallback：图片不可用时退回文字，底色转中性底，绝不出现裂图。",
      "variant": "状态 fallback"
    },
    {
      "id": "badge",
      "group": "02 组件状态",
      "title": "带角标",
      "desc": "角标位挂在线状态或未读数，绝对定位不改变头像尺寸。",
      "variant": "slots.badge"
    },
    {
      "id": "disabled",
      "group": "02 组件状态",
      "title": "禁用",
      "desc": "状态 disabled：置灰用于已离职或已停用的主体。",
      "variant": "disabled=true"
    }
  ],
  "related": [
    {
      "slug": "mobile-list",
      "why": "头像作为列表行的前缀位时用列表承载整行；只有单张头像时用本组件"
    },
    {
      "slug": "mobile-badge",
      "why": "需要数字角标时用徽标组件包裹头像；只表示在线状态用本组件自带的 badge 位"
    },
    {
      "slug": "mobile-tag",
      "why": "要用文字标注状态或分类时用标签；头像只承载主体身份"
    }
  ]
}