--- title: "头像" description: "用一张小图片代表一个人、一个团队或一个项目；没有图片时，用姓名缩写或一个字形；形状是圆形或圆角方形，有三种尺寸。多个头像可以显示成相互交叠的一组，并数出其余的数量。它是一张图片，从不是控件。" url: "https://tanrei.chnotchy.com/zh-cn/components/avatar/" last_updated: 2026-10-23T21:17:12.000Z --- # 头像 > 用一张小图片代表一个人、一个团队或一个项目；没有图片时，用姓名缩写或一个字形；形状是圆形或圆角方形，有三种尺寸。多个头像可以显示成相互交叠的一组，并数出其余的数量。它是一张图片，从不是控件。 ## 概览 头像表明某样东西属于谁：帖子的作者、对话中的人、任务的负责人。它绘制一张图片，没有图片时也总有东西可画。它从不响应指针、按键或焦点。 在 Web 上它是 ``，多个放在一起则是 ``。其他平台尚未实现。 ### 用法 **Web** ```html

李华

smart_toy ``` **React** ```tsx import { Avatar, AvatarGroup } from '@tanrei/react'; {reviewers.slice(0, 3).map((person) => ( ))} ``` ## 规格 - Category: Communication - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/avatar/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/avatar.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3 Expressive-like (Material 3 Expressive-inspired) (`m3-expressive-like`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/avatar`). - React: `Avatar` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-avatar` | lagging | | SwiftUI | `TanreiAvatar` | planned | | Jetpack Compose | `TanreiAvatar` | planned | | Flutter | `TanreiAvatar` | planned | | React Native | `Avatar` | planned | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `src` (prop) | `src` | `url` | `model` | `image` | `source` | | `label` (prop) | `label` | `name` | `name` | `name` | `name` | | `decorative` (prop) | `decorative` | `isDecorative` | `decorative` | `decorative` | `decorative` | | `overflowLabel` (prop) | `overflowLabel` | `overflowLabel` | `overflowDescription` | `overflowSemanticLabel` | `overflowAccessibilityLabel` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `container`: The square box of the avatar's size, clipped to a circle or to a rounded square, with a quiet fill that shows behind the initials, the glyph, a picture that is still loading and the transparent parts of a picture. It carries no state: nothing about it answers a pointer, a press or focus. - `image` (optional): The picture the product names by its address, filling the box and clipped to its shape. Drawn once it has loaded. - `label` (optional): The initials the product gives, drawn at the centre of the box where there is no picture to show. A picture of a name, not text to be read: the name is the avatar's label. - `icon` (optional): The fallback glyph, at the centre of the box, where there is neither a picture nor initials: the glyph the product names, or the system's own (a person for a circle, a neutral mark for a square). - `group` (optional): Several avatars drawn as one row in which each lies a little over the one before it, with a gap around each so that two pictures are read as two. The group gives its avatars their size and shape. - `overflow` (optional): The last box of a group that does not draw all its members: an avatar-sized box in the fallback's colors holding a plus sign and the number of members not drawn. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `src` | `string` | `""` | `src` | The address of the picture. Empty, or a picture that has not loaded or cannot be loaded, draws the fallback: initials where the product gave some, otherwise a glyph. | | `label` | `string` | `""` | `label` | The name of the person or the thing the avatar stands for, in full ("Ada Lovelace", "Design team"). Not drawn: it is the avatar's accessible name while decorative is false. In the group form it is the group's name ("Reviewers"). | | `initials` | `string` | `""` | `initials` | The one or two characters drawn where there is no picture ("AL", "山"). The product makes them: which characters stand for a name depends on its writing system and its order, which the avatar cannot know. Never read by assistive technology. | | `decorative` | `boolean` | `false` | `decorative` | True hides the avatar from assistive technology, for an avatar that stands beside the same name in visible text (a byline, a list row, a comment's header), so the name is read once. False, for an avatar that stands alone, exposes it as an image named by label. Ignored for the members of a group. | | `size` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | Small (24) stands beside one line of text: a byline, a table cell, a mention. Medium (40) is a list row's or a comment's avatar. Large (56) heads a person's own page or card. A group gives its size to every member. A design system may add values. | | `shape` | `enum`: `circle`, `square` | `"circle"` | `shape` | Circle is a person. Square, a rounded square, is something that is not one person: a team, a project, an organisation, a bot. A group gives its shape to every member. A design system may add values. | | `max` | `number` | `0` | — | Group form only. The most boxes the group draws, the overflow box included; 0 draws every member. A whole number of 2 or more: with more members than this, the group draws one fewer member than max and then the overflow box. | | `total` | `number` | — | — | Group form only. How many members there are, where the product gives the group fewer than exist (the first five of a team of two hundred). Null counts the members given. | | `overflowLabel` | `string` | `""` | — | Group form only. What assistive technology reads for the overflow box: the whole sentence in the product's language, with one place, {count}, which the group fills with the number of members not drawn ("{count} more", "ほか{count}人"). Written once as the product's words, it serves every group. A sentence that is right for every number, or a prop set per count where the language needs another form for one. Empty reads the product's words; with neither, the drawn text ("+12"). | ### Slots | Slot | Description | | --- | --- | | `icon` | The fallback glyph: a glyph of the system's icon set, by name, drawn through the platform's icon helper where there is neither a picture nor initials. Empty draws the system's own fallback glyph. | ### Item: `member` One avatar of a group: an avatar with its own picture, name, initials and glyph, drawn at the group's size and shape. It is a Avatar. Names: Web `tanrei-avatar`, SwiftUI `TanreiAvatar`, Jetpack Compose `TanreiAvatar`, Flutter `TanreiAvatar`, React Native `Avatar`. | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `src` | `string` | `""` | `src` | The address of the member's picture. | | `label` | `string` | `""` | `label` | The member's name. Always exposed in a group: the names are what the group says. | | `initials` | `string` | `""` | `initials` | The member's initials, drawn where there is no picture. | ### States `enabled` ### Accessibility - Role: `img` - Labeling: An avatar that stands alone is an image named by label, the full name of the person or the thing, whatever it draws; the initials, the glyph and the picture's address are never read. An avatar beside the same name in visible text is decorative and hidden. A group is a group named by its label, holding one named image for each member it draws and, last, the overflow's text (overflowLabel, or the drawn count). Inside a link or a Button, the avatar's label is part of that element's name. - Minimum target size: yes - Not interactive: the avatar takes no input and no focus (AVT-7), so there is no target to size and minimumTarget holds trivially. An avatar that is pressed is inside a link or a Button, and that element meets the minimum target by its own spec; a small (24) avatar alone in a link needs the link's target, not its own box, to be large enough. - Decorative or named is the product's decision and cannot be seen from the avatar: beside "Ada Lovelace" in text a named avatar would be read as "Ada Lovelace, image, Ada Lovelace". The rule the docs page gives: if deleting the avatar loses a name, it is named; otherwise it is decorative. - The name is the name, not a description of the picture: "Ada Lovelace", never "Photo of Ada Lovelace" and never the initials. - Contrast in the default system: the initials, the count and the glyph are on-surface-variant on surface-container-highest, a pair the token invariants hold to 4.5:1 for secondary content on every surface tone. The fill against the surface around it is not held to a ratio: the avatar is not a control, and what it says is its name. - A picture brings its own colors, which the avatar does not check. A picture with a pale edge on a pale surface loses its outline; the avatar draws no ring around a picture, so a product whose pictures are often pale chooses the square or gives the surface behind them a tone. - A badge on an avatar (AVT-12) says that something is waiting, in the badge's one color and with the badge's label in words. Presence (online, away, busy) is a status that a color alone would carry; say it in words beside the name, with a tag where it needs a mark. - Forced colors (AVT-13): every fallback gains an edge in the text color; pictures are left alone. - A group's overflow box is text, not a control. Where the people it counts matter (who else can see this), the product lists them: a link or a Button beside the group that opens the full list. ### Behaviour Requirements in EARS form, each with its stable id. - **AVT-1** THE avatar SHALL draw a square box whose side is the container size of its size (comp.avatar.container.size.small for small, comp.avatar.container.size.medium for medium, comp.avatar.container.size.large for large), with the corners of its shape (comp.avatar.container.shape.circle for circle, comp.avatar.container.shape.square for square), never larger than half the box's side (a circle where the value is sys.shape.corner.full) and eased by sys.shape.corner-smoothing, filled with comp.avatar.container.color, and SHALL clip everything it draws to that shape. THE avatar SHALL lay itself out inline with the text or the row it is placed in, as one unbreakable box that the layout neither stretches nor shrinks, and SHALL draw no edge and no elevation. - **AVT-2** THE avatar SHALL draw exactly one of three things at the centre of its box (and two only for the cross-fade in which its picture arrives, AVT-4), the first of these that it has: the picture src names, once that picture has loaded (AVT-3, AVT-4); else initials, where initials is not empty (AVT-5); else a glyph (AVT-6). THE avatar SHALL never draw an empty box, a broken-picture mark or the picture's address, and SHALL NOT make initials out of label. - **AVT-3** WHILE the picture of src has loaded THE avatar SHALL draw it over the whole box, scaled so that it covers the box with its proportions kept and its centre on the box's centre, clipped to the box's shape, over comp.avatar.container.color (which shows through the picture's transparent parts), and SHALL draw neither initials nor a glyph. THE avatar SHALL NOT mirror, tint or otherwise change the picture in any layout direction or scheme. - **AVT-4** WHILE src is not empty and its picture has not yet loaded THE avatar SHALL draw its fallback (AVT-2) in the box, at the avatar's full size, so that nothing changes place when the picture arrives; WHEN the picture has loaded THE avatar SHALL fade it in over the fallback while the fallback fades out beneath it, one cross-fade of opacity over comp.avatar.motion.picture-duration on comp.avatar.motion.picture-easing (sys.motion.role.state.default and sys.motion.easing.state), in which nothing changes place or size; reduced motion keeps it, as a change of opacity is not motion (MOT-6). WHERE the picture loads while the avatar draws its first frames (MOT-3), or the platform already holds it when the avatar asks for it (in its memory of the pictures it has loaded), THE avatar SHALL draw it at once, in the fallback's place. IF the picture cannot be loaded THE avatar SHALL keep the fallback, SHALL NOT ask for the picture again by itself, and in debug builds SHALL report the address that failed. WHEN src changes THE avatar SHALL draw the fallback at once, until the new picture has loaded and fades in. WHILE src is empty THE avatar SHALL ask for nothing. - **AVT-5** WHERE the avatar draws initials THE avatar SHALL set them on one line at the centre of the box, in the text style of its size (comp.avatar.label.typescale.small for small, comp.avatar.label.typescale.medium for medium, comp.avatar.label.typescale.large for large) and in comp.avatar.label.color, as the product wrote them: it SHALL NOT change their case, and SHALL draw no more than the first two characters as a reader counts them (grapheme clusters), reporting in debug builds a value that is longer. THE avatar SHALL lay the initials out as text of their own direction, isolated from the text around the avatar, and SHALL keep them from assistive technology. - **AVT-6** WHERE the avatar draws a glyph THE avatar SHALL draw the glyph of its icon slot, or, where the slot is empty, the system's fallback glyph for its shape (person for circle, category for square), in a box of the icon size of its size (comp.avatar.icon.size.small for small, comp.avatar.icon.size.medium for medium, comp.avatar.icon.size.large for large) at the centre of the avatar, in comp.avatar.icon.color, with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, and SHALL keep it from assistive technology. - **AVT-7** THE avatar SHALL NOT take pointer, touch or keyboard input, SHALL NOT take focus or be a stop in the focus order, and SHALL NOT change anything it draws under a pointer, a press or focus: it has no hovered, focused, pressed, selected or disabled state, draws no state layer, no ripple and no focus indicator, and emits no event. - **AVT-8** WHERE the avatar is placed inside an element that takes input (a link, a Button, a list item, a chip, a card that is pressed as a whole) THE avatar SHALL let input over it reach that element, SHALL stay as it is drawn while that element is hovered, focused or pressed (the state and the focus indicator are drawn by that element, on its own container), and SHALL NOT become a second target inside it; WHILE decorative is false THE avatar SHALL add its label to that element's content in reading order, so that a link or a Button that holds an avatar and nothing else is named by the avatar's label. An avatar that leads somewhere or opens something is that composition: the avatar has no destination and no action of its own. - **AVT-9** WHILE decorative is false and label is not empty THE avatar SHALL be exposed to assistive technology as one image named by label, whether it draws a picture, initials or a glyph, and SHALL expose nothing else: not the initials, not the glyph's name, not the picture's address, and not its size or shape. WHILE decorative is true THE avatar SHALL expose nothing. IF decorative is false, label is empty and the product gives it no name (AVT-24) THE avatar SHALL expose nothing and in debug builds report that an avatar has no name. - **AVT-10** WHEN label, initials, the icon slot's glyph, size or shape changes THE avatar SHALL draw and expose the new value at once, without a motion, and SHALL NOT announce the change by itself. - **AVT-11** WHILE the text size is enlarged THE avatar SHALL keep its box at the container size of its size and its glyph at the size of AVT-6, and SHALL let its initials, and a group's count (AVT-17), follow their text style as it grows, no larger than the glyph's box of the same size (comp.avatar.icon.size.small for small, comp.avatar.icon.size.medium for medium, comp.avatar.icon.size.large for large), so that they still stand whole inside the box: an avatar is a picture and is enlarged with the page, not with the text, as a glyph's box is, while the letters it holds grow as far as the box leaves room for them. - **AVT-12** WHERE the avatar is the anchor of a badge THE avatar SHALL be drawn exactly as it is without one: its square box is the anchor's bounds, the badge is placed by that box's top-end corner and drawn outside the avatar's clip (BDG-1, BDG-3, BDG-7), and the badge's label is added to the avatar's description after its name (BDG-8). THE avatar SHALL have no dot, count or status of its own. - **AVT-13** WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE avatar SHALL draw an edge sys.border.hairline wide in the platform's text color inside its box, following its shape, and its initials or its glyph in that text color, so that a fallback whose fill the mode removes is still a bounded mark; THE avatar SHALL leave a picture's own colors as they are. - **AVT-14** THE avatar SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the avatar is shown THE avatar SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows. A single avatar is the same in both directions but for its glyph (AVT-15): its picture is never mirrored and its initials keep their own order (AVT-5). - **AVT-15** WHERE the layout direction is right-to-left THE avatar SHALL draw the glyph of its icon slot mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place nor its size, color and fill. THE avatar SHALL NOT mirror a glyph itself, and SHALL NOT mirror its picture or its initials. - **AVT-16** WHERE the avatar is given members THE avatar SHALL be a group: it SHALL draw its members in one row that does not wrap, in the order they are given from the start edge, each as an avatar of the group's size and shape with that member's own picture, initials or glyph (AVT-2 to AVT-6), and SHALL ignore its own src, initials, icon slot and decorative. Each box after the first SHALL lie over the end of the one before it by the overlap of the group's size (comp.avatar.group.overlap.small for small, comp.avatar.group.overlap.medium for medium, comp.avatar.group.overlap.large for large) and be drawn above it, and every box SHALL be surrounded, outside its own edge and following its shape, by a gap comp.avatar.group.outline.width wide in comp.avatar.group.outline.color that takes no room in the layout. THE group SHALL be as wide as its boxes less their overlaps, and as high as one box. - **AVT-17** WHILE the group has more members than max and max is 2 or more THE group SHALL draw the first max less one members and then, as its last box, an overflow box: a box of the group's size and shape filled with comp.avatar.container.color, placed and surrounded as a member is (AVT-16), holding on one line, in the label style of the group's size (AVT-5) and comp.avatar.label.color, a plus sign followed by the number of members not drawn. WHILE max is 0, or the group has no more members than max, THE group SHALL draw every member and no overflow box, unless total says more exist (AVT-18). THE overflow box SHALL take no input and SHALL NOT be a control: showing the members it counts is the product's, beside the group. - **AVT-18** WHILE total is greater than the number of members the group is given THE group SHALL count as not drawn every member up to total, and SHALL draw the overflow box with that number after the members it draws: where the members given fit within max less one, or max is 0, all of them are drawn before it. THE group SHALL write the number in the current locale's digits with no grouping separator, SHALL draw 99 followed by a plus sign in place of a number above 99, at every size, so that the box never holds more than three characters (the exact number stays in overflowLabel, AVT-19), and SHALL lay the sign and the number out as one left-to-right run isolated from the text around it, so that the plus sign stays before the digits in a right-to-left layout. - **AVT-19** THE group SHALL be exposed to assistive technology as one group named by its label, holding in order one image for each member it draws, each named by that member's label whatever decorative says, and then, where it draws an overflow box, one text: overflowLabel — from the instance's prop or, WHILE that is empty, from the product's words of the key avatarGroupOverflowLabel — with its place {count} filled by the number of members not drawn, in the current locale's digits with no grouping separator and never cut at 99 as the drawn text is (AVT-18); else the drawn text. Another text between braces, and a brace that opens or closes nothing, SHALL be read as written and reported in debug builds; a sentence without {count} SHALL be read as written and reported in debug builds, because it does not say how many. THE gaps SHALL be kept from assistive technology. IF the group's label is empty THE group SHALL expose its members without a group's name and in debug builds report that a group has no name; IF a member's label is empty THE group SHALL expose nothing for that member and in debug builds report it. - **AVT-20** WHERE the layout direction is right-to-left THE group SHALL lay its row out from the right: the first member is at the right, each following box lies over the left end of the one before it and above it, and the overflow box is the leftmost; the order assistive technology reads SHALL stay the order given. - **AVT-21** WHEN the group's members, max, total, size or shape change THE group SHALL draw and expose the new row at once, without a motion, and SHALL NOT announce the change by itself. - **AVT-22** WHEN size or shape names a value that the active design system does not have THE avatar SHALL render with the default value's tokens, and in debug builds report the unknown value. IF max is 1, negative or not a whole number THE group SHALL draw as for 0 and in debug builds report it; IF total is not null and is less than the number of members given, negative or not a whole number THE group SHALL count the members given and in debug builds report it. - **AVT-23** IF the avatar is a group and every member has been removed THE group SHALL draw nothing, take no space and expose nothing. IF max, total or overflowLabel is set on an avatar that has no members THE avatar SHALL ignore it and in debug builds report it. - **AVT-24** WHERE the platform has ARIA attributes (the web), an avatar's host and a group's host carries its role (AVT-9, AVT-19) itself, so what the product writes on it is not moved, but for a name: WHILE label is not empty THE avatar SHALL hold the product's aria-label and aria-labelledby on that host as their data-aria- twins, so that label is its whole name although the platform gives aria-labelledby the precedence, and WHEN label is emptied SHALL give them back as they were written; WHILE label is empty a name the product gives so — aria-label, or aria-labelledby naming an element — SHALL be its name and SHALL NOT be reported as having none in debug builds (AVT-9, AVT-19). WHILE an avatar's label is empty and decorative is false (or it is a member of a group) a name the product gives so SHALL make it one image named by that name, as AVT-9 says of its label: an image the product names is a named image. WHILE an avatar is decorative and not a member, or a group has no members (AVT-23), it exposes nothing, and THE avatar SHALL hold them as well, giving them back when it is exposed again. WHEN the product removes one, or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaLabelledByElements) to null, THE avatar SHALL take it away. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.avatar.…` → `--tanrei-comp-avatar-…`). #### `tanrei.comp.avatar` | Token | Type | Value | | --- | --- | --- | | `comp.avatar.container.size.small` | `dimension` | `24px` | | `comp.avatar.container.size.medium` | `dimension` | `40px` | | `comp.avatar.container.size.large` | `dimension` | `56px` | | `comp.avatar.container.shape.circle` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.avatar.container.shape.square` | `dimension` | `{tanrei.sys.shape.corner.small}` | | `comp.avatar.container.color` | `color` | `{tanrei.sys.color.surface-container-highest}` | | `comp.avatar.label.typescale.small` | `typography` | `{tanrei.sys.typescale.caption}` | | `comp.avatar.label.typescale.medium` | `typography` | `{tanrei.sys.typescale.label}` | | `comp.avatar.label.typescale.large` | `typography` | `{tanrei.sys.typescale.heading-3}` | | `comp.avatar.label.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.avatar.icon.size.small` | `dimension` | `{tanrei.sys.icon.extra-small}` | | `comp.avatar.icon.size.medium` | `dimension` | `{tanrei.sys.icon.medium}` | | `comp.avatar.icon.size.large` | `dimension` | `{tanrei.sys.icon.large}` | | `comp.avatar.icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.avatar.motion.picture-duration` | `duration` | `{tanrei.sys.motion.role.state.default}` | | `comp.avatar.motion.picture-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` | | `comp.avatar.group.overlap.small` | `dimension` | `{tanrei.sys.space.space25}` | | `comp.avatar.group.overlap.medium` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.avatar.group.overlap.large` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.avatar.group.outline.width` | `dimension` | `{tanrei.sys.border.thick}` | | `comp.avatar.group.outline.color` | `color` | `{tanrei.sys.color.surface}` | ## 指南 ### 何时使用 当一张小图片比单独的姓名更快地告诉用户某样东西属于谁、属于什么时，使用头像：署名行、评论、人员列表中的一行、个人资料的顶部。它是一张图片，仅此而已。它没有悬停，没有焦点，没有按下，也没有事件。 | 你需要 | 使用 | | --- | --- | | 人身上的一个圆点或一个计数（“3 条未读”） | 围在头像外面的[徽标](https://tanrei.chnotchy.com/zh-cn/components/badge/)。 | | 通向个人资料的头像 | 里面放着头像的[链接](https://tanrei.chnotchy.com/zh-cn/components/link/)。 | | 打开菜单的头像 | 里面放着头像的[按钮](https://tanrei.chnotchy.com/zh-cn/components/button/)。 | | 可以被选中或移除的人 | [纸片](https://tanrei.chnotchy.com/zh-cn/components/chip/)。 | | 在线状态（在线、离开） | 姓名旁边的文字；需要标记的地方再加一个 [Tag](https://tanrei.chnotchy.com/zh-cn/components/tag/)。 | ### 它绘制什么 头像绘制下面这些东西里它拥有的第一样： 1. `src` 的图片，在它加载完成之后。 2. 你给出的 `initials`。 3. 它的 `icon` 插槽里的字形。 4. 系统自己的字形：圆形用一个人形，方形用一个中性的标记。 方框从第一次绘制起就保持自己的尺寸。图片加载期间，在它的位置上绘制替代内容，图片到达后淡入，替代内容同时淡出。浏览器已经持有的图片会立即绘制。头像周围的东西都不会移动。无法加载的图片会留下替代内容：没有图片损坏的标记，头像也不会再次请求。 ### 姓名缩写 头像不会根据姓名生成缩写。用哪些字符代表一个姓名，取决于它的文字系统，也取决于哪一部分写在前面，而你的产品已经知道这些。请在 `initials` 中给出： | 姓名 | `initials` | | --- | --- | | Ada Lovelace | `AL` | | 山田 花子 | `山` 或 `山田` | | 王小明 | `王` | | ليلى حسن | `لح` | | किरण राव | `किरा` | 头像最多绘制两个字符，按读者数字符的方式来数，所以带附加符号的字母或者连写的音节绝不会被切成两半。它按写下的样子绘制，不改变大小写。 ### 尺寸和形状 | `size` | 边长 | 用于 | | --- | --- | --- | | `small` | 24 | 一行文本的旁边：署名行、表格单元格、提及。 | | `medium`（默认） | 40 | 列表中的一行、评论。 | | `large` | 56 | 某个人自己的页面或卡片的顶部。 | | `shape` | 用于 | | --- | --- | | `circle`（默认） | 一个人。 | | `square` | 不是某一个人的东西：团队、项目、组织、机器人。 | 所有替代内容都使用同一种低调的填充。没有按人区分的颜色：不表达任何含义的颜色，系统里没有。 ### 图片 - 提供一张方形图片，边长至少是头像边长的两倍，这样它在高密度屏幕上仍然清晰。其他比例的图片会围绕中心裁剪。 - `loading="lazy"` 会等到头像靠近窗口时才请求图片。在很长的列表里使用它。 - `referrerpolicy` 和 `crossorigin` 会按你写的原样传给图片。头像两样都不替你选：把你页面的哪些信息告诉图片所在的主机，由你决定。 ### 组 组把它的成员画成一行。每个成员只压住前一个成员一点点（按尺寸为 2、4 或 8），因此并排的两个字母缩写保持完整、不会被误读；每个成员周围都有一圈表面颜色的间隙。 - `max` 是组最多绘制的方框数，溢出框也算在内。六名成员加上 `max="4"`，是三名成员和“+3”。组绝不绘制“+1”：那等于花掉一个方框去藏起一张脸。 - 交给组的成员比实际的少时，`total` 是真实的总数。三名成员、`max="4"` 和 `total="240"`，是三名成员和“99+”：超过 99 时，任何尺寸的方框都写“99+”，所以方框里最多只有三个字符。确切的数字请写在 `overflow-label` 里，读屏读的是它。 - 组把自己的 `size` 和 `shape` 交给每一个成员。 - 放在页面表面以外的其他表面上时，把 `--tanrei-comp-avatar-group-outline-color` 设为那个表面的颜色。 - 溢出框是文本，不是控件。用户需要看到还有谁的地方，在组的旁边放一个链接或按钮。 ### 脚本到达之前 `` 在自己的 shadow root 里绘制，所以服务器渲染的页面在脚本运行之前，它的位置上什么都不显示。加载 `@tanrei/web/avatar.css`，每个头像就会保留一个与它的尺寸和形状相符的方框，页面也就不会发生位移。在那之前，图片、姓名缩写和名称都不显示。对于不运行脚本也必须能读的页面，请在装饰性的头像旁边用文本写出姓名。 带 `max` 的组在脚本数完成员之前，会显示你交给它的每一个成员。如果这绝不能让页面发生位移，就只把组要绘制的成员交给它，其余的用 `total` 表示。 ### 推荐 - 给每个单独出现的头像一个 `label`：完整的姓名。 - 头像位于写着同一个姓名的文本旁边时，给它设置 `decorative`。 - 给每个人都提供 `initials`，这样图片缺失或加载缓慢时，仍然看得出是谁。 - 在整个产品里，同一类东西使用同一种形状。 ### 避免 - 不要在头像上放处理函数。把它放进链接或按钮，它们才有各种状态和焦点指示。 - 不要在标签里写“……的照片”。标签就是姓名。 - 不要用你自己的颜色、圆环或圆点来表示状态。计数用徽标，在线状态用文字说明。 - 不要把头像用于装饰性的图片或标题里的标志（logo）。它代表的是某个人，或者用户以其身份行事的某样东西。 ## 无障碍 ### 组件负责的部分 - 单独使用时，它是一张由 `label` 命名的图像，无论它绘制的是图片、姓名缩写还是字形。姓名缩写、字形的名称和图片的地址绝不会被朗读。 - 设置 `decorative` 后，它对辅助技术隐藏。 - 在链接或按钮里面时，它的标签成为该元素的名称，按在头像上也会传到该元素。 - 围在它外面的徽标，会把徽标的标签加在头像的名称之后。 - 组是一个由它的 `label` 命名的组。它为自己绘制的每个成员各包含一张有名称的图像，按给定的顺序排列，然后是溢出框的文本。它没有绘制的成员不会暴露出来。 - 它不接受任何输入，也不接受焦点，所以不在焦点顺序中增加停靠点。 - 文本放大时，它像图标一样保持自己的方框大小。姓名缩写随文本变大，到该尺寸的字形框为止，在方框里保持完整。 - 在强制颜色模式下，所有替代内容都会多出一道文本颜色的边线。图片保留自己的颜色。 - 在从右到左的布局中，组从右侧开始。图片和姓名缩写绝不镜像，“+3”的加号仍然在数字之前。 - 没有名称的头像、超过两个字符的姓名缩写、加载失败的图片，以及未知的尺寸或形状，都会在调试构建中报告。 ### 需要你做的事 - 为每个头像决定它是有名称的，还是装饰性的。规则是：如果删掉这个头像会丢掉一个姓名，它就是有名称的；否则就是装饰性的。 - 用页面所用的语言编写一次 `overflowLabel`，在数字的位置写上占位符 `{count}`（“`还有 {count} 人`”）——写在组上，或用 `setWords({ avatarGroupOverflowLabel })` 为整个产品设置。组会填入未画出的人数，即使画的是 99+，填入的也是实际人数。请写出对任何数字都正确的句子；如果语言需要按数字变换形式，就按数字替换。没有它时，“+3”会按画出来的样子朗读。 - 给链接里的小头像留出足够的按压空间。头像宽 24；链接自己必须满足最小目标。 - 图片带有它自己的颜色。图片的边缘常常偏浅的地方，给它们背后的表面加一层色调。