前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载TDesign 小程序 UI 库tdesign-miniprogram中的 Avatar头像组件用于展示用户头像信息除纯展示外还可点击进入个人详情等交互场景其配套组件 AvatarGroup 支持多个头像的层叠展示与超出数量折叠。本文基于仓库内 Avatar 组件 API 文档 展开完整覆盖两个组件的 Props、Events、Slots、External Classes 与 CSS Variables并结合 avatar.ts、avatar-group.ts 等源码剖析父子关系继承、图片加载失败处理与级联偏移的底层实现。一、组件概览与引入方式根据 中文文档 的说明Avatar 组件用于展示用户头像信息且明确标注了渲染框架支持情况Skyline、WebView 均支持。组件目录下同时提供微信原生小程序实现packages/components/avatar与 UniApp 适配实现packages/uniapp-components/avatar本文以微信原生小程序版本为准。引入方式为在小程序的app.json全局引入或页面/组件的index.json局部引入中配置usingComponents: { t-avatar: tdesign-miniprogram/avatar/avatar, t-avatar-group: tdesign-miniprogram/avatar-group/avatar-group }二、头像类型与典型使用场景组件文档给出了六类演示场景对应仓库中 avatar 演示用例图片头像传入image属性展示网络/本地图片字符头像不传image与icon通过默认插槽传入文本如用户昵称首字图标头像传入icon属性值为字符串时表示图标名称值为Object时透传至 icon 组件徽标头像通过badge-props在头像右上角叠加小红点或数字继承 Badge 组件的全部特性组合头像纯展示 / 带操作t-avatar-group包裹多个t-avatar可设置max折叠超出部分头像尺寸size支持small/medium/large及任意px、rpx值。从 avatar.wxml 的模板结构可以确认内容渲染存在明确的优先级wx:if{{image isImgExist}}—— 有图片地址且未标记加载失败时渲染t-imageimage-props可透传mode、lazy、loading、shape、webp、error等属性默认mode为aspectFillwx:elif判断_icon非空对象时渲染 icon 模板否则渲染__text容器并挂载默认slot /用于字符头像或完全自定义内容。三、Avatar APIAvatar Props| 名称 | 类型 | 默认值 | 描述 | 必传 | | -- | -- | -- | -- | -- | | style | Object | - | 样式 | N | | custom-style | Object | - | 样式一般用于开启虚拟化组件节点场景 | N | | alt | String | - | 头像替换文本仅当图片加载失败时有效 | N | | badge-props | Object | - | 头像右上角提示信息继承 Badge 组件的全部特性如小红点或数字。TS 类型BadgeProps详见 Badge API 文档详细类型定义 | N | | bordered | Boolean | false | 已废弃。是否显示外边框 | N | | hide-on-load-failed | Boolean | false | 加载失败时隐藏图片 | N | | icon | String / Object | - | 图标。值为字符串表示图标名称值为Object类型时透传至icon| N | | image | String | - | 图片地址 | N | | image-props | Object | - | 透传至 Image 组件。TS 类型ImageProps详见 Image API 文档详细类型定义 | N | | shape | String | - | 形状可选项circle/round。优先级高于 AvatarGroup.shapeAvatar 单独存在时默认值为 circle父组件 AvatarGroup 存在时默认值由 AvatarGroup.shape 决定。TS 类型ShapeEnum通用类型定义 | N | | size | String | - | 尺寸示例值small/medium/large/24px/38px 等。优先级高于 AvatarGroup.sizeAvatar 单独存在时默认值为 medium父组件 AvatarGroup 存在时默认值由 AvatarGroup.size 决定 | N |以上定义与 props.ts 中的实际注册值一一对应例如alt默认值为、hide-on-load-failed默认值为false、icon的 type 为null同时接受 String 与 Object。Avatar Events| 名称 | 参数 | 描述 | | -- | -- | -- | | error | - | 图片加载失败时触发 |Avatar Slots| 名称 | 描述 | | -- | -- | | - | 默认插槽自定义内容区域内容 |Avatar External Classes| 类名 | 描述 | | -- | -- | | t-class | 根节点样式类 | | t-class-alt | 替代文本样式类 | | t-class-content | 内容样式类 | | t-class-icon | 图标样式类 | | t-class-image | 图片样式类 |外部类在 avatar.ts#L15-L21 中注册其中t-class-image作用于包裹图片/图标/文本的内层容器是自定义头像背景与圆角的关键入口。四、Avatar 源码实现剖析4.1 与 AvatarGroup 的父子关系及属性继承avatar.ts#L34-L47 通过relations声明了与avatar-group的 ancestor 关系relations: RelationsOptions { ../avatar-group/avatar-group: { type: ancestor, linked(parent) { this.parent parent; this.setData({ shape: this.data.shape || parent.data.shape || circle, size: this.data.size || parent.data.size, bordered: true, }); }, }, };这解释了文档中shape/size 优先级高于 AvatarGroup的语义子组件自身设置时优先未设置时回退到父组件的值两者都没有时 shape 兜底为circle。同时可以看到一旦头像处于组内bordered会被强制置为true即组合头像默认带白色描边分隔对应 less 中的--border样式这也是组合头像层叠不粘连的视觉基础。4.2 图片加载失败处理与 error 事件avatar.ts#L49-L64 中定义了两个 observers配合 avatar.ts#L73-L78 的onLoadError方法构成完整的容错链路image变化时会重置isImgExist: true源码注释明确说明目的是避免切换后无法重新渲染——即先失败的头像换回有效地址后能重新加载onLoadError根据hideOnLoadFailed决定isImgExistfalse 时图片节点从模板中消失回退到 icon 或默认插槽文本无论是否隐藏都会triggerEvent(error, e.detail)对应文档中的error事件detail透传自 t-image 的错误信息。4.3 尺寸与类名计算的 WXS 逻辑avatar.wxs 在渲染层完成两个关键计算getClass拼装--circle/--round形状类与--border-{size}边框类当 size 含px时边框宽度按medium档取值保证自定义尺寸下边框视觉一致getSize以正则^([0-9])(px|rpx)$匹配自定义尺寸rpx会按windowWidth * n / 750换算为 px并按font-size (px / 8) * 3 2动态计算文字字号——因此字符头像在任意自定义尺寸下都能保持比例协调。预设尺寸的宽高、字号、边框宽度等均在 avatar.less 中以 CSS 变量方式定义如 large 为 128rpx、medium 96rpx、small 80rpx。五、AvatarGroup APIAvatarGroup Props| 名称 | 类型 | 默认值 | 描述 | 必传 | | -- | -- | -- | -- | -- | | style | Object | - | 样式 | N | | custom-style | Object | - | 样式一般用于开启虚拟化组件节点场景 | N | | cascading | String | left-up | 图片之间的层叠关系可选值左侧图片在上和右侧图片在上。可选项left-up/right-up。TS 类型CascadingValuetype CascadingValue left-up \| right-up详细类型定义 | N | | collapse-avatar | String | - | 头像数量超出时会出现一个头像折叠元素该元素内容可自定义默认为N。示例5、...、更多| N | | max | Number | - | 能够同时显示的最多头像数量 | N | | shape | String | - | 形状优先级低于 Avatar.shape。可选项circle/round。TS 类型ShapeEnum通用类型定义 | N | | size | String | - | 尺寸示例值small/medium/large/24px/38px 等。优先级低于 Avatar.size | N |AvatarGroup Events| 名称 | 参数 | 描述 | | -- | -- | -- | | collapsed-item-click | - | 点击头像折叠元素触发 |AvatarGroup Slots| 名称 | 描述 | | -- | -- | | - | 默认插槽自定义内容区域内容 | | collapse-avatar | 自定义collapse-avatar显示内容 |AvatarGroup External Classes| 类名 | 描述 | | -- | -- | | t-class | 根节点样式类 | | t-class-content | 内容样式类 | | t-class-image | 图片样式类 |六、AvatarGroup 源码实现剖析6.1 级联层叠的偏移类计算avatar-group.ts#L51-L64 的setClass方法解析cascading参数并生成根节点类名const direction cascading.split(-)[0]; // left | right const classList [ name, ${prefix}-class, ${name}-offset-${direction}, ${name}-offset-${direction}-${size.indexOf(px) -1 ? medium : size || medium}, ];即cascadingleft-up会生成t-avatar-group-offset-left t-avatar-group-offset-left-medium。配合 avatar-group.less偏移量通过 CSS 变量--td-avatar-margin-left注入到每个头像 wrapper 的margin-left上三种尺寸均为calc(-1 * spacer)形成负向重叠z-index 则通过 Less 递归 mixin.generate-z-index按nth-child逐个递减初始值 50从而实现左侧在上的层叠次序right-up时方向反转视觉上变为右侧在上。cascading、size任一变化都会通过 observers 重新触发setClass。6.2 max 截断与折叠元素avatar-group.ts#L66-L76 的handleMax在ready阶段执行handleMax() { const { max } this.data; const len this.$children.length; if (!max || max len) return; const restAvatars this.$children.splice(max, len - max); restAvatars.forEach((child) { child.hide(); // 子组件内 setData({ isShow: false })wrapper 变为 display:none }); }被截断的头像并非从 DOM 中移除而是调用子组件的hide()方法以display: none隐藏见 avatar.wxs#L27-L29 的getStyles这样保留节点状态头像动态增删时逻辑仍然可恢复。折叠元素在 avatar-group.wxml 中当max max length时渲染默认折叠元素其内部是一个iconuser-add的t-avatar加上collapseAvatar文本未传文本时仅显示user-add图标配合样式呈现N效果bindtaponCollapsedItemClick触发collapsed-item-click事件。若开发者通过collapse-avatar命名插槽注入了自定义内容less 中__collapse--slot:not(:empty) __collapse--default { display: none }的规则会让默认折叠元素自动隐藏两种展示方式互斥且无缝切换。七、CSS Variables 自定义样式组件提供了下列 CSS 变量可用于自定义样式默认值与 avatar.less、avatar-group.less 中的 Less 变量映射一致| 名称 | 默认值 | 说明 | | -- | -- | -- | | --td-avatar-group-init-z-index | 50 | 组合头像初始 z-index递归递减生成层叠次序 | | --td-avatar-group-line-spacing | calc(spacer / 4) | 组合头像上下留白wrapper padding | | --td-avatar-group-margin-left-large | calc(-1 * spacer) | large 尺寸组合头像重叠偏移量 | | --td-avatar-group-margin-left-medium | calc(-1 * spacer) | medium 尺寸组合头像重叠偏移量 | | --td-avatar-group-margin-left-small | calc(-1 * spacer) | small 尺寸组合头像重叠偏移量 | | --td-avatar-bg-color | brand-color-light-active | 头像背景色 | | --td-avatar-border-color | #fff | 头像边框颜色 | | --td-avatar-border-width-large | 6rpx | 大尺寸边框宽度 | | --td-avatar-border-width-medium | 4rpx | 中尺寸边框宽度 | | --td-avatar-border-width-small | 2rpx | 小尺寸边框宽度 | | --td-avatar-circle-border-radius | radius-circle | 圆形头像圆角 | | --td-avatar-content-color | brand-color | 头像文字颜色 | | --td-avatar-icon-large-font-size | 64rpx | large 图标字号 | | --td-avatar-icon-medium-font-size | 48rpx | medium 图标字号 | | --td-avatar-icon-small-font-size | font-size-xl | small 图标字号 | | --td-avatar-large-width | 128rpx | large 头像宽高 | | --td-avatar-margin-left | 0 | 单个头像左边距组内被 offset 类覆写 | | --td-avatar-medium-width | 96rpx | medium 头像宽高 | | --td-avatar-round-border-radius | radius-default | 方形圆角头像圆角 | | --td-avatar-small-width | 80rpx | small 头像宽高 | | --td-avatar-text-large-font-size | font-size-xl | large 文字字号 | | --td-avatar-text-medium-font-size | font-size-m | medium 文字字号 | | --td-avatar-text-small-font-size | font-size-base | small 文字字号 |由于所有 Less 变量均以var(--td-xxx, 默认值)形式消费开发者只需在页面或组件样式中覆写对应变量如--td-avatar-bg-color、--td-avatar-border-width-medium即可在不改动组件源码的情况下定制外观。八、小结与相关文件Avatar 组件的核心设计可以概括为三点内容三级回退image → icon → 插槽文本、属性优先级继承Avatar 自身属性 AvatarGroup 继承值 内置默认值、状态化容错加载失败标记可随 image 变化自动重置。AvatarGroup 则通过负 margin 递减 z-index 实现级联层叠通过hide()软隐藏 折叠元素实现max截断并保留collapse-avatar插槽与collapsed-item-click事件用于业务定制。本文引用的仓库文件清单packages/components/avatar/README.en-US.md英文 API 文档本文主体packages/components/avatar/README.md中文文档与演示说明packages/components/avatar/avatar.ts组件逻辑relations/observers/error 处理packages/components/avatar/avatar.wxml渲染模板与内容优先级packages/components/avatar/avatar.wxs类名与自定义尺寸计算packages/components/avatar/avatar.less样式与 CSS 变量packages/components/avatar/props.ts 与 packages/components/avatar/type.ts属性注册与 TS 类型packages/components/avatar-group/avatar-group.ts分组逻辑setClass/handleMaxpackages/components/avatar-group/avatar-group.wxml折叠元素模板packages/components/avatar-group/avatar-group.less级联偏移与 z-index 生成packages/components/avatar-group/props.ts 与 packages/components/avatar-group/type.ts分组属性与CascadingValue类型packages/components/avatar/test组件测试与演示用例赞分享前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载相关推荐Ant Design Blazor Avatar 组件完整指南图片、图标、字符与 AvatarGroup 头像组实战Ant Design Blazor Avatar 组件完整指南图片、图标、字符与 AvatarGroup 头像组实战 Avatars头像用于代表用户、人物UI组件前端Semi Design Avatar 头像组件完全指南尺寸、颜色、Slot 扩展与 AvatarGroup 头像组实战Semi Design Avatar 头像组件完全指南尺寸、颜色、Slot 扩展与 AvatarGroup 头像组实战 Avatar头像是 Semi De前端UI组件设计系统Varlet AvatarGroup 头像组组件详解头像堆叠偏移、垂直排列与源码实现原理Varlet AvatarGroup 头像组组件详解头像堆叠偏移、垂直排列与源码实现原理 头像组AvatarGroup是 Varlet 移动端/桌面端组件UI组件前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考