头像

用于表示用户个人资料图片或姓名缩写

import { Avatar } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Avatar.Root>
      <Avatar.Fallback name="Segun Adebayo" />
      <Avatar.Image src="https://bit.ly/sage-adebayo" />
    </Avatar.Root>
  )
}

用法

import { Avatar, AvatarGroup } from "@chakra-ui/react"

<AvatarGroup>
  <Avatar.Root>
    <Avatar.Fallback />
    <Avatar.Image />
  </Avatar.Root>
</AvatarGroup>

信息

如果您倾向于使用封闭式组件组合，请查看下面的代码片段。

示例

尺寸

使用 size 属性来改变头像的尺寸

import { Avatar, For, HStack } from "@chakra-ui/react"

const Demo = () => {
  return (
    <HStack gap="3">
      <For each={["xs", "sm", "md", "lg", "xl", "2xl"]}>
        {(size) => (
          <Avatar.Root size={size} key={size}>
            <Avatar.Fallback name="Segun Adebayo" />
            <Avatar.Image src="https://bit.ly/sage-adebayo" />
          </Avatar.Root>
        )}
      </For>
    </HStack>
  )
}

变体

使用 variant 属性来改变头像的变体

import { Avatar, For, HStack } from "@chakra-ui/react"

const Demo = () => {
  return (
    <HStack gap="3">
      <For each={["solid", "outline", "subtle"]}>
        {(variant) => (
          <Avatar.Root key={variant} variant={variant}>
            <Avatar.Fallback name="Segun Adebayo" />
          </Avatar.Root>
        )}
      </For>
    </HStack>
  )
}

形状

使用 shape 属性来改变头像的形状，从 rounded（圆形）到 square（方形）

import { Avatar, HStack } from "@chakra-ui/react"

const Demo = () => {
  return (
    <HStack gap="4">
      <Avatar.Root shape="square" size="lg">
        <Avatar.Fallback name="Dan Abramov" />
        <Avatar.Image src="https://bit.ly/dan-abramov" />
      </Avatar.Root>
      <Avatar.Root shape="rounded" size="lg">
        <Avatar.Fallback name="Segun Adebayo" />
        <Avatar.Image src="https://bit.ly/sage-adebayo" />
      </Avatar.Root>
      <Avatar.Root shape="full" size="lg">
        <Avatar.Fallback name="Random User" />
        <Avatar.Image src="https://images.unsplash.com/photo-1531746020798-e6953c6e8e04" />
      </Avatar.Root>
    </HStack>
  )
}

颜色

使用 colorPalette 属性来改变头像的颜色

灰色

红色

绿色

蓝色

青色

粉色

紫色

青绿色

橙色

黄色

import { Avatar, Stack, Text } from "@chakra-ui/react"
import { colorPalettes } from "compositions/lib/color-palettes"

const Demo = () => {
  return (
    <Stack gap="2" align="flex-start">
      {colorPalettes.map((colorPalette) => (
        <Stack key={colorPalette} align="center" direction="row" gap="10">
          <Text minW="8ch">{colorPalette}</Text>
          <Avatar.Root colorPalette={colorPalette}>
            <Avatar.Fallback name="Segun Adebayo" />
            <Avatar.Image src="https://bit.ly/sage-adebayo" />
          </Avatar.Root>
          <Avatar.Root colorPalette={colorPalette}>
            <Avatar.Fallback name="Segun Adebayo" />
          </Avatar.Root>
          <Avatar.Root colorPalette={colorPalette}>
            <Avatar.Fallback />
          </Avatar.Root>
        </Stack>
      ))}
    </Stack>
  )
}

回退

当未提供名称或图片加载失败时，将 Avatar.Icon 作为回退渲染。

import { Avatar, HStack } from "@chakra-ui/react"

const Demo = () => {
  return (
    <HStack>
      <Avatar.Root>
        <Avatar.Fallback name="Oshigaki Kisame" />
        <Avatar.Image src="https://bit.ly/broken-link" />
      </Avatar.Root>
      <Avatar.Root colorPalette="teal">
        <Avatar.Fallback name="Sasuke Uchiha" />
        <Avatar.Image src="https://bit.ly/broken-link" />
      </Avatar.Root>
      <Avatar.Root colorPalette="red">
        <Avatar.Fallback />
        <Avatar.Image src="https://bit.ly/broken-link" />
      </Avatar.Root>
    </HStack>
  )
}

随机颜色

结合 colorPalette 属性和一些自定义逻辑，动态改变头像的颜色

import { Avatar, HStack } from "@chakra-ui/react"

const colorPalette = ["red", "blue", "green", "yellow", "purple", "orange"]

const pickPalette = (name: string) => {
  const index = name.charCodeAt(0) % colorPalette.length
  return colorPalette[index]
}

const Demo = () => {
  return (
    <HStack>
      <Avatar.Root colorPalette={pickPalette("Shane Nelson")}>
        <Avatar.Fallback name="Shane Nelson" />
      </Avatar.Root>
      <Avatar.Root colorPalette={pickPalette("Brook Lesnar")}>
        <Avatar.Fallback name="Brook Lesnar" />
      </Avatar.Root>
      <Avatar.Root colorPalette={pickPalette("John Lennon")}>
        <Avatar.Fallback name="John Lennon" />
      </Avatar.Root>
    </HStack>
  )
}

边框

使用 outline* 属性来为头像添加边框

import { Avatar, HStack, defineStyle } from "@chakra-ui/react"

const ringCss = defineStyle({
  outlineWidth: "2px",
  outlineColor: "colorPalette.500",
  outlineOffset: "2px",
  outlineStyle: "solid",
})

const Demo = () => {
  return (
    <HStack gap="4">
      <Avatar.Root css={ringCss} colorPalette="pink">
        <Avatar.Fallback name="Random" />
        <Avatar.Image src="https://randomuser.me/api/portraits/men/70.jpg" />
      </Avatar.Root>
      <Avatar.Root css={ringCss} colorPalette="green">
        <Avatar.Fallback name="Random" />
        <Avatar.Image src="https://randomuser.me/api/portraits/men/54.jpg" />
      </Avatar.Root>
      <Avatar.Root css={ringCss} colorPalette="blue">
        <Avatar.Fallback name="Random" />
        <Avatar.Image src="https://randomuser.me/api/portraits/men/42.jpg" />
      </Avatar.Root>
    </HStack>
  )
}

分组

使用 Group 组件将多个头像分组显示

import { Avatar, AvatarGroup } from "@chakra-ui/react"

const Demo = () => {
  return (
    <AvatarGroup gap="0" spaceX="-3" size="lg">
      <Avatar.Root>
        <Avatar.Fallback name="Uchiha Sasuke" />
        <Avatar.Image src="https://cdn.myanimelist.net/r/84x124/images/characters/9/131317.webp?s=d4b03c7291407bde303bc0758047f6bd" />
      </Avatar.Root>

      <Avatar.Root>
        <Avatar.Fallback name="Baki Ani" />
        <Avatar.Image src="https://cdn.myanimelist.net/r/84x124/images/characters/7/284129.webp?s=a8998bf668767de58b33740886ca571c" />
      </Avatar.Root>

      <Avatar.Root>
        <Avatar.Fallback name="Uchiha Chan" />
        <Avatar.Image src="https://cdn.myanimelist.net/r/84x124/images/characters/9/105421.webp?s=269ff1b2bb9abe3ac1bc443d3a76e863" />
      </Avatar.Root>
      <Avatar.Root variant="solid">
        <Avatar.Fallback>+3</Avatar.Fallback>
      </Avatar.Root>
    </AvatarGroup>
  )
}

堆叠

使用 AvatarGroup 组件时，您可以使用 stacking 属性来改变头像的堆叠顺序

import { Avatar, AvatarGroup, Stack } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Stack>
      <AvatarGroup size="lg" stacking="last-on-top">
        {items.map((item) => (
          <Avatar.Root key={item.name}>
            <Avatar.Fallback name={item.name} />
            <Avatar.Image src={item.src} />
          </Avatar.Root>
        ))}
        <Avatar.Root>
          <Avatar.Fallback>+3</Avatar.Fallback>
        </Avatar.Root>
      </AvatarGroup>

      <AvatarGroup size="lg" stacking="first-on-top">
        {items.map((item) => (
          <Avatar.Root key={item.name}>
            <Avatar.Fallback name={item.name} />
            <Avatar.Image src={item.src} />
          </Avatar.Root>
        ))}
        <Avatar.Root>
          <Avatar.Fallback>+3</Avatar.Fallback>
        </Avatar.Root>
      </AvatarGroup>

      <AvatarGroup size="lg" spaceX="1" borderless>
        {items.map((item) => (
          <Avatar.Root key={item.name}>
            <Avatar.Fallback name={item.name} />
            <Avatar.Image src={item.src} />
          </Avatar.Root>
        ))}
        <Avatar.Root>
          <Avatar.Fallback>+3</Avatar.Fallback>
        </Avatar.Root>
      </AvatarGroup>
    </Stack>
  )
}

const items = [
  {
    src: "https://cdn.myanimelist.net/r/84x124/images/characters/9/131317.webp?s=d4b03c7291407bde303bc0758047f6bd",
    name: "Uchiha Sasuke",
  },
  {
    src: "https://cdn.myanimelist.net/r/84x124/images/characters/7/284129.webp?s=a8998bf668767de58b33740886ca571c",
    name: "Baki Ani",
  },
  {
    src: "https://cdn.myanimelist.net/r/84x124/images/characters/9/105421.webp?s=269ff1b2bb9abe3ac1bc443d3a76e863",
    name: "Uchiha Chan",
  },
]

人物形象

这里是使用 Avatar 组件显示用户人物形象的示例。

John Mason

john.mason@example.com

Melissa Jones

melissa.jones@example.com

import { Avatar, HStack, Stack, Text } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Stack gap="8">
      {users.map((user) => (
        <HStack key={user.email} gap="4">
          <Avatar.Root>
            <Avatar.Fallback name={user.name} />
            <Avatar.Image src={user.avatar} />
          </Avatar.Root>
          <Stack gap="0">
            <Text fontWeight="medium">{user.name}</Text>
            <Text color="fg.muted" textStyle="sm">
              {user.email}
            </Text>
          </Stack>
        </HStack>
      ))}
    </Stack>
  )
}

const users = [
  {
    id: "1",
    name: "John Mason",
    email: "john.mason@example.com",
    avatar: "https://i.pravatar.cc/300?u=iu",
  },
  {
    id: "2",
    name: "Melissa Jones",
    email: "melissa.jones@example.com",
    avatar: "https://i.pravatar.cc/300?u=po",
  },
]

徽章

通过组合 Float 和 Circle 组件，在头像右下角显示一个徽章

import { Avatar, Circle, Float } from "@chakra-ui/react"

const Demo = () => {
  return (
    <Avatar.Root colorPalette="green" variant="subtle">
      <Avatar.Fallback name="Dari Ann" />
      <Float placement="bottom-end" offsetX="1" offsetY="1">
        <Circle
          bg="green.500"
          size="8px"
          outline="0.2em solid"
          outlineColor="bg"
        />
      </Float>
    </Avatar.Root>
  )
}

溢出

这里是使用 Menu 和 Avatar 组件处理头像溢出情况的示例。

import { Avatar, Group, Menu, Portal } from "@chakra-ui/react"

const names = [
  "Naruto Uzumaki",
  "Sakura Haruno",
  "Kakashi Hatake",
  "Hinata Hyuga",
  "Shikamaru Nara",
]
const maxAvatars = 3

const Demo = () => {
  const { items, overflow } = partition(names, maxAvatars)
  return (
    <Group gap="0" spaceX="2">
      {items.map((item) => (
        <Avatar.Root key={item} colorPalette={pickPalette(item)}>
          <Avatar.Fallback name={item} />
        </Avatar.Root>
      ))}
      {overflow.length > 0 && (
        <Menu.Root positioning={{ placement: "bottom" }}>
          <Menu.Trigger rounded="full" focusRing="outside">
            <Avatar.Root variant="outline">
              <Avatar.Fallback>+{overflow.length}</Avatar.Fallback>
            </Avatar.Root>
          </Menu.Trigger>
          <Portal>
            <Menu.Positioner>
              <Menu.Content>
                {overflow.map((item) => (
                  <Menu.Item value={item} key={item}>
                    <Avatar.Root size="xs" colorPalette={pickPalette(item)}>
                      <Avatar.Fallback name={item} />
                    </Avatar.Root>
                    {item}
                  </Menu.Item>
                ))}
              </Menu.Content>
            </Menu.Positioner>
          </Portal>
        </Menu.Root>
      )}
    </Group>
  )
}

const colorPalette = ["red", "blue", "green", "yellow", "purple", "orange"]

const pickPalette = (name: string) => {
  const index = name.charCodeAt(0) % colorPalette.length
  return colorPalette[index]
}

const partition = (arr: string[], max: number) => {
  const items = []
  const overflow = []
  for (const item of arr) {
    if (items.length < max) items.push(item)
    else overflow.push(item)
  }
  return { items, overflow }
}

Next.js

这里是使用 Next.js Image 组合头像的示例。

import { getImageProps } from "next/image"

function Demo() {
  const imageProps = getImageProps({
    src: "/image.png",
  })
  return (
    <Avatar.Root>
      <Avatar.Fallback name="Segun Adebayo" />
      <Avatar.Image {...imageProps} />
    </Avatar.Root>
  )
}

状态管理

访问头像状态和方法的另一种方式是使用 RootProvider 组件和 useAvatar 状态管理钩子。

未加载

"use client"

import { Avatar, Code, Stack, useAvatar } from "@chakra-ui/react"

const Demo = () => {
  const avatar = useAvatar()
  return (
    <Stack align="flex-start">
      <Avatar.RootProvider value={avatar}>
        <Avatar.Image src="https://bit.ly/sage-adebayo" />
        <Avatar.Fallback name="Segun Adebayo" />
      </Avatar.RootProvider>
      <Code>{avatar.loaded ? "loaded" : "not loaded"}</Code>
    </Stack>
  )
}

封闭式组件

这里是如何为封闭式组件组合设置头像的示例。

import {
  Avatar as ChakraAvatar,
  AvatarGroup as ChakraAvatarGroup,
} from "@chakra-ui/react"
import * as React from "react"

type ImageProps = React.ImgHTMLAttributes<HTMLImageElement>

export interface AvatarProps extends ChakraAvatar.RootProps {
  name?: string
  src?: string
  srcSet?: string
  loading?: ImageProps["loading"]
  icon?: React.ReactElement
  fallback?: React.ReactNode
}

export const Avatar = React.forwardRef<HTMLDivElement, AvatarProps>(
  function Avatar(props, ref) {
    const { name, src, srcSet, loading, icon, fallback, children, ...rest } =
      props
    return (
      <ChakraAvatar.Root ref={ref} {...rest}>
        <ChakraAvatar.Fallback name={name}>
          {fallback || icon}
        </ChakraAvatar.Fallback>
        <ChakraAvatar.Image src={src} srcSet={srcSet} loading={loading} />
        {children}
      </ChakraAvatar.Root>
    )
  },
)

export const AvatarGroup = ChakraAvatarGroup

如果您想自动将封闭式组件添加到您的项目，请运行以下命令

npx @chakra-ui/cli snippet add avatar

属性

根组件

属性	默认值	类型
`colorPalette`	`'灰色'`	`'灰色' \| '红色' \| '橙色' \| '黄色' \| '绿色' \| '青色' \| '蓝色' \| '青绿色' \| '紫色' \| '粉色'` 组件的颜色调色板
`size`	`'md'`	`'full' \| '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` 组件的尺寸
`variant`	`'subtle'`	`'solid' \| 'subtle' \| 'outline'` 组件的变体
`shape`	`'full'`	`'square' \| 'rounded' \| 'full'` 组件的形状
`asChild`		`boolean` 使用提供的子元素作为默认渲染元素，并结合其属性和行为。欲了解更多详情，请阅读我们的组合指南。
`ids`		`Partial<{ root: string; image: string; fallback: string }>` 头像中元素的 ID。有助于组合。
`onStatusChange`		`(details: StatusChangeDetails) => void` 当图片加载状态改变时调用的函数。
`borderless`		`'true' \| 'false'` 组件的无边框状态
`as`		`React.ElementType` 要渲染的底层元素。
`unstyled`		`boolean` 是否移除组件的样式。

回退

属性	默认值	类型
`asChild`		`boolean` 使用提供的子元素作为默认渲染元素，并结合其属性和行为。欲了解更多详情，请阅读我们的组合指南。
`name`		`string`
`icon`		`React.ReactElement`

图片

属性	默认值	类型
`asChild`		`boolean` 使用提供的子元素作为默认渲染元素，并结合其属性和行为。欲了解更多详情，请阅读我们的组合指南。

Alert

徽章

头像

.css-vfo6uh{color:var(--chakra-colors-fg);-webkit-text-decoration:underline;text-decoration:underline;text-underline-offset:3px;text-decoration-thickness:2px;text-decoration-color:var(--chakra-colors-border-emphasized);font-weight:500;}用法

用法