amis Avatar 头像组件完全指南JSON 配置、变量绑定与事件交互【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amisAvatar 头像组件是 amis 低代码框架中用于展示用户头像、缩略图或文字标识的基础展示型组件。通过一行 JSON 配置即可渲染图片、文字或图标三种形态的头像并支持从上下文中动态绑定数据、失败降级置换、形状与尺寸定制以及事件派发适用于用户列表、评论模块、个人信息页等场景。读完本文你将掌握 Avatar 组件的全部属性用法、源码级渲染机制与事件动作配置方案。组件定位与适用场景在 amis 中Avatar 是一个基础展示组件type: avatar在官方文档 components/avatar.md 中被定义用来显示用户头像。从源码看amis 将 Avatar 拆分为两层实现渲染器层packages/amis/src/renderers/Avatar.tsx负责 JSON Schema 解析、变量解析resolveVariableAndFilter与事件派发dispatchEvent基础组件层packages/amis-ui/src/components/Avatar.tsx负责 DOM 结构、图片加载失败处理与 gap 自适应缩放。因此它既可以在普通页面中使用也可以作为其他展示类组件如 Card的内嵌元素出现。在 amis-editor 插件 中它被登记为布局场景static scene [layout]的基础组件支持在可视化编辑器中通过「属性 / 外观 / 事件」三个面板直接拖拽配置。基本使用一行 JSON 显示图片头像最简单的用法是直接通过src指定图片地址{ type: avatar, src: https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg }渲染器会将src交给 amis-ui 的img标签输出。这里有一个细节值得注意渲染器在传值前执行了src src || defaultAvatar见 Avatar.tsx也就是说当src为空时会自动回退到defaultAvatar占位图这是defaultAvatar属性的实际生效位置。文字与图标无图场景的替代方案当没有图片地址时可以用文字或图标填充头像{ type: avatar, text: AM }{ type: avatar, icon: fa fa-user }icon的默认值是fa fa-user在 Avatar.tsx 的AvatarField.render中通过默认参数注入这意味着即使不配置任何内容组件也会渲染一个默认用户图标。优先级规则当src、text、icon同时存在时依次按src→text→icon的优先级渲染。这一规则在渲染器的render分支中实现见 amis-ui/src/components/Avatar.tsx优先走img分支其次走文字span分支最后才渲染Icon。换句话说text的优先级永远高于icon这点在下文的降级置换场景中同样成立。动态图片与文字从上下文变量取值src、text、icon三个属性都支持 amis 变量语法可从当前数据域中动态取值。渲染器在渲染前会依次调用isPureVariable判断并用resolveVariableAndFilter解析见 Avatar.tsx。{ data: { myAvatar: https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg }, type: page, body: [ { type: avatar, icon: fa fa-user, src: $myAvatar }, { type: avatar, icon: fa fa-user, src: $other }, { type: avatar, src: $other, icon: fa fa-user, text: avatar } ] }上面的例子演示了三种典型结果第一个头像$myAvatar取到了图片地址正常显示图片第二个头像$other在上下文中不存在取值为空后src落空于是降级渲染默认的icon第三个头像同样取不到图片但由于text优先级高于icon最终显示文字 avatar。这一行为在 渲染器测试用例Renderer:avatar var中有完整覆盖测试通过makeEnv构建页面数据域后断言快照输出。注意此处取不到数据导致的空 src与下文图片地址本身加载失败是两种不同情况处理路径并不相同。形状控制圆形、方形与圆角通过shape可以切换头像外形可选值为circle圆形默认、square正方形、rounded圆角[ { type: avatar, shape: square, text: AM }, { type: avatar, shape: rounded, text: AM, style: { marginLeft: 10px } } ]从样式源码看_avatar.scss 中Avatar--square将border-radius设为0%Avatar--rounded设为10%而基础样式默认border-radius: 50%构成圆形。也就是说形状本质上就是三个圆角类名Avatar--circle/Avatar--square/Avatar--rounded的切换shape的默认值circle在 amis-ui Avatar 组件的 defaultProps 中定义。尺寸控制预设大小与自定义像素size支持字符串预设和数字像素两种写法默认default[ { type: avatar, size: large, icon: fa fa-user }, { type: avatar, size: default, icon: fa fa-user }, { type: avatar, size: small, icon: fa fa-user }, { type: avatar, size: 60, src: https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg }, { type: avatar, src: https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg }, { type: avatar, size: 20, src: https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg } ]三种预设字符串对应的实际尺寸来自 _properties.scss 的 CSS 变量定义size 值头像尺寸图标尺寸large48px--Avatar-size-large20pxdefault40px--Avatar-width同时是--Avatar-size-default继承--fontSizeLgsmall32px--Avatar-size-small12px当size是数字时amis-ui 渲染逻辑 会生成内联样式{height: size, width: size, lineHeight: size px}直接以像素控制宽高。注意文档属性表中把字符串类型写成default | normal | small但实际源码渲染器与基础组件两处的联合类型均为small | default | large其中normal是历史兼容写法效果等同默认 40px。这些预设值都通过px2rem()转换会随根字号缩放适合需要响应式适配的主题体系。编辑器插件的默认 scaffold 则以 40px 为默认尺寸DefaultSize 40见 Avatar.tsx。gap文字与边界的距离控制gap控制文字字符类型内容距离左右两侧边界的像素默认值 4[ { type: avatar, text: ejson, gap: 2 }, { type: avatar, text: ejson, gap: 7 } ]它的底层实现并不只是简单加内边距amis-ui 在挂载和更新时调用setScaleByGap()见 amis-ui/src/components/Avatar.tsx先测量文字节点宽度avatarChildrenRef.offsetWidth与头像容器宽度avatarRef.offsetWidth当gap * 2 容器宽度时计算diff 容器宽度 - gap * 2若文字宽度超过可用宽度则按比例diff / childrenWidth缩放文字并通过transform: scale(...) translateX(-50%)保持水平居中。因此gap实际上是文字过多时与边框保持的最小距离文字超出时会自动等比缩小而非溢出。这一逻辑在componentDidUpdate中会在src变化导致hasImg切换、text、children或gap改变时重新计算。fit图片拉伸方式fit控制图片在头像容器内的缩放方式默认cover取值与 CSSobject-fit完全对应[ { type: avatar, fit: cover, src: https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg }, { type: avatar, fit: fill, src: https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg }, { type: avatar, fit: contain, src: https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg }, { type: avatar, fit: none, src: https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg }, { type: avatar, fit: scale-down, src: https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg } ]各取值含义cover等比例缩放并裁剪铺满容器默认值适合正方形头像fill拉伸填满不保持比例contain完整容纳在容器内留白短边none按原尺寸展示超出部分裁剪scale-down取none与contain中较小的结果。实现上amis-ui 渲染 会将该值直接注入img的style.objectFit因此在 _avatar.scss 中img本身是width/height: 100%具体裁切行为完全交由浏览器 object-fit 完成。编辑器插件还为其提供了中文说明等比例裁剪长边、等比例留空短边、拉伸图片填满、按原尺寸裁剪。draggable是否允许拖动图片draggable控制图片是否可被鼠标拖拽例如拖到其他窗口[ { type: avatar, fit: cover, src: https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg, draggable: false }, { type: avatar, fit: cover, src: https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg, draggable: true } ]它直接透传给img draggable{draggable}见 amis-ui/src/components/Avatar.tsx等同于原生 img 的draggable属性。默认不设置该值时浏览器行为由全局默认决定需要阻止用户拖走头像图片时显式设置为false即可。onError图片加载失败后的置换逻辑当图片地址本身加载失败时注意不包括变量取值为空的情况默认行为是不做任何置换、只保留原src。通过onError可以开启失败后降级为 text 或 icon的能力{ type: avatar, src: empty, text: avatar, onError: return true; }onError是一个字符串它会被渲染器通过new Function(event, onError)动态构造为函数执行见 amis/src/renderers/Avatar.tsx参数是 React 合成事件可通过event.nativeEvent获取原生 DOM 事件。该函数需要返回 boolean 值返回true图片加载失败后用text优先或icon其次进行替换显示返回false维持默认行为不进行置换。底层判定发生在 amis-ui 的 handleImageLoadErrorhasImg onError ? !onError(event) : false随后render中hasImg false时不再走img分支而是顺延到文字/图标分支。之所以不包含变量取空的情况是因为渲染器层已经用src || defaultAvatar做了兜底空值根本不会进入img的onError路径。如果构造onError字符串时语法错误渲染器会console.warn并回退为默认处理器始终返回false。样式定制与 className可以通过style直接控制外层 DOM 的背景与文字颜色{ type: avatar, text: AM, style: { background: #DB3E35, color: #FFFFFF } }style透传到外层span的style与数字size生成的宽高样式合并见 amis-ui/src/components/Avatar.tsx所以也可以用它覆盖背景色、透明度等任意 CSS 属性className追加到外层span的 class用于配合项目自定义样式默认背景色来自主题变量--Avatar-bg: #d1d5db灰底见 _properties.scss可通过覆盖该 CSS 变量统一调整头像底色。此外_avatar.scss 定义了 hover 效果鼠标悬停时图片和图标transform: scale(1.1)轻微放大属于组件内置交互无需额外配置。编辑器插件在「外观」面板还提供了长度、高度、圆角、文字样式、内外边距、边框、背景、阴影、透明度等可视化配置项底层统一映射到style对象见 amis-editor/src/plugin/Avatar.tsx。属性表总览属性名类型默认值说明classNamestring外层 dom 的类名styleobject外层 dom 的样式fitcontain|cover|fill|none|scale-downcover图片相对容器的缩放方式对应 CSSobject-fitsrcstring图片地址支持变量defaultAvatarstring占位图src为空时使用textstring文字支持变量优先级高于 iconiconstringfa fa-user图标支持变量shapecircle|square|roundedcircle形状圆形、正方形、圆角10% 圆角sizenumber|small|default|largedefault预设大小分别为 32 / 40 / 48px数字则按像素设置宽高gapnumber4文字距离左右边界的最小像素文字过宽时自动缩放altstring图片无法显示时的替代文本对应原生altdraggableboolean图片是否允许拖动crossOriginanonymous|use-credentials|图片的 CORS 属性设置透传至img crossOriginonErrorstring图片加载失败处理函数体字符串返回true时降级为 text/icon 置换补充说明badge角标属性在渲染器 Schema 中同样存在见 packages/amis/src/renderers/Avatar.tsx渲染器外层包裹了withBadge装饰器因此 Avatar 也支持在头像右上角叠加 amis 角标。事件交互click / mouseenter / mouseleave事件派发能力需要 amis 6.1.0 及以上版本。Avatar 会对外派发click、mouseenter、mouseleave三个事件可通过onEvent监听并配合actions执行动作在 actions 中通过${事件参数名}或${event.data.[事件参数名]}获取事件数据事件机制的详细说明见 事件动作文档。click鼠标点击时触发可通过${event.context.nativeEvent}获取原生鼠标事件对象{ type: avatar, onEvent: { click: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.context.nativeEvent.type} } } ] } } }mouseenter鼠标移入时触发{ type: avatar, onEvent: { mouseenter: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.context.nativeEvent.type} } } ] } } }mouseleave鼠标移出时触发{ type: avatar, onEvent: { mouseleave: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.context.nativeEvent.type} } } ] } } }三个事件均不携带额外业务数据参数可用的数据就是event.context.nativeEvent原生事件对象。实现层面渲染器的三个autobind处理器handleClick/handleMouseEnter/handleMouseLeave统一调用dispatchEvent(e, data)派发事件见 packages/amis/src/renderers/Avatar.tsx测试用例 avatar.test.tsx 通过fireEvent.click/mouseEnter/mouseLeave验证了三个事件均能正确触发toast动作并携带配置的msg。实战组合示例用户列表头像结合本文所有能力一个典型的用户列表头像配置如下{ type: page, data: { users: [ { name: Alice, avatar: https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg }, { name: Bob } ] }, body: [ { type: each, name: users, items: { type: avatar, size: large, shape: rounded, src: ${avatar}, defaultAvatar: https://suda.cdn.bcebos.com/amis/images/ai-fake-face.jpg, text: ${name|truncate:1}, onError: return true;, style: { background: #1890ff, color: #fff }, onEvent: { click: { actions: [ { actionType: toast, args: { msg: 点击了 ${name} } } ] } } } } ] }该示例展示了变量绑定、占位图回退、失败置换、形状尺寸、样式与事件动作的完整组合有头像地址的用户显示图片无头像地址的用户先尝试defaultAvatar图片加载失败时再置换为姓名首字母文字点击后弹出提示。总结Avatar 头像组件以最小配置成本覆盖了头像展示的全部常见诉求图片 / 文字 / 图标三种内容形态、src→text→icon的严格优先级、变量动态取值、shape与size的形态控制、gap的自适应文字缩放、fit的图片裁切、onError的失败置换以及 click / mouseenter / mouseleave 三个事件动作。如果需要在可视化编辑器中使用可直接拖入「头像」组件在属性面板中切换图片 / 图标 / 文字类型并调整外观生成的 JSON 与手写配置完全一致对应插件源码 packages/amis-editor/src/plugin/Avatar.tsx。【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考