頭像

頭像是一種使用者身分識別的圖形化呈現方式。

簡介

頭像元件可用於在選單、表格和聊天等位置顯示使用者的圖形資訊。

基本用法

import Avatar from '@mui/joy/Avatar';

預設情況下，頭像元件會顯示一個通用的「人物」圖示。您可以將此圖示替換為文字字串或圖片。

<Avatar />
<Avatar>JG</Avatar>
<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />

<Avatar />
<Avatar>JG</Avatar>
<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />

按下 Enter 鍵開始編輯

文字頭像

將字串包裝在頭像元件周圍以顯示文字。請注意，頭像的設計最多可舒適地容納兩個字母——例如，使用者的姓名縮寫

<Avatar>RE</Avatar>

<Avatar>RE</Avatar>

按下 Enter 鍵開始編輯

圖片頭像

透過在 src 屬性內定義路徑，將圖片插入頭像中，就像您對 HTML <img> 元素所做的那樣。請務必為 alt 屬性撰寫有意義的描述。

<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
<Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
<Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />

<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
<Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
<Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />

按下 Enter 鍵開始編輯

圖片回退

如果在載入頭像的圖片時發生錯誤，它將回退到以下替代方案（依此順序）

提供的子字串
alt 文字的第一個字母
預設通用圖示

<Avatar alt="Remy Sharp" src="/broken-image.jpg">
  BT
</Avatar>
<Avatar alt="Remy Sharp" src="/broken-image.jpg" />
<Avatar src="/broken-image.jpg" />

<Avatar alt="Remy Sharp" src="/broken-image.jpg">
  BT
</Avatar>
<Avatar alt="Remy Sharp" src="/broken-image.jpg" />
<Avatar src="/broken-image.jpg" />

按下 Enter 鍵開始編輯

客製化

變體

頭像元件支援 Joy UI 的四種全域變體：solid、soft（預設）、outlined 和 plain。

<Avatar variant="solid" />
<Avatar variant="soft" />
<Avatar variant="outlined" />
<Avatar variant="plain" />

<Avatar variant="solid" />
<Avatar variant="soft" />
<Avatar variant="outlined" />
<Avatar variant="plain" />

按下 Enter 鍵開始編輯

尺寸

頭像元件提供三種尺寸：sm、md（預設）和 lg

<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" size="sm" />
<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" size="md" />
<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" size="lg" />

<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" size="sm" />
<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" size="md" />
<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" size="lg" />

按下 Enter 鍵開始編輯

與頭像群組一起使用

import AvatarGroup from '@mui/joy/AvatarGroup';

使用頭像群組元件將多個頭像組合在一起。

<AvatarGroup>
  <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
  <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
  <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
  <Avatar>+3</Avatar>
</AvatarGroup>

<AvatarGroup>
  <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
  <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
  <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
  <Avatar>+3</Avatar>
</AvatarGroup>

按下 Enter 鍵開始編輯

群組內的數量

頭像群組不提供內建的 props 來控制群組內頭像的最大或總數。這是刻意保持開放式的，以便為您提供更廣泛的客製化選項。

下面的示範顯示了一個頭像群組的範例，該群組最多可容納五個頭像；前四個之後的所有頭像都集中在第五個頭像中，其中顯示了隱藏的總數

+20

<AvatarGroup>
  {avatars.map((avatar) => (
    <Avatar key={avatar.alt} {...avatar} />
  ))}
  {!!surplus && <Avatar>+{surplus}</Avatar>}
</AvatarGroup>

<AvatarGroup>
  {avatars.map((avatar) => (
    <Avatar key={avatar.alt} {...avatar} />
  ))}
  {!!surplus && <Avatar>+{surplus}</Avatar>}
</AvatarGroup>

按下 Enter 鍵開始編輯

一致的外觀

頭像元件公開了有意義的 CSS 變數，以便與頭像群組進行溝通。您可以將這些變數應用於其他非頭像元件，以模仿頭像在群組內的外觀。這種客製化技術使您的介面更具變更彈性，因為應用於頭像的任何樣式變更也將應用於群組中的其他元件。

這是一個使用圖示按鈕的範例，其樣式由頭像的 CSS 變數定義

重疊順序

預設情況下，群組中的第一個頭像位於第二個頭像的後面，第二個頭像位於第三個頭像的後面，依此類推。您可以透過反轉頭像的順序並在頭像群組中使用 CSS flexDirection: row-reverse 屬性來反轉重疊順序

<AvatarGroup sx={{ flexDirection: 'row-reverse' }}>
  <Avatar>+3</Avatar>
  <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
  <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
  <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
</AvatarGroup>

<AvatarGroup sx={{ flexDirection: 'row-reverse' }}>
  <Avatar>+3</Avatar>
  <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
  <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
  <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
</AvatarGroup>

按下 Enter 鍵開始編輯

垂直堆疊

若要垂直呈現頭像群組，請新增 CSS writing-mode: vertical-rl 屬性，並將內部元素（如果存在）旋轉 -90 度。

<AvatarGroup sx={{ writingMode: 'vertical-rl' }}>
  <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
  <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
  <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
  <Avatar sx={{ transform: 'rotate(-90deg)' }}>+3</Avatar>
</AvatarGroup>

<AvatarGroup sx={{ writingMode: 'vertical-rl' }}>
  <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
  <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
  <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
  <Avatar sx={{ transform: 'rotate(-90deg)' }}>+3</Avatar>
</AvatarGroup>

按下 Enter 鍵開始編輯

與徽章一起使用

import Badge from '@mui/joy/Badge';

將頭像元件與徽章結合使用，以視覺化方式傳達有關使用者狀態的更複雜資訊

CSS 變數 playground

試用頭像元件可用的 CSS 變數，以查看設計如何變更。您可以使用這些變數透過 sx 屬性和主題來自訂元件。

<AvatarGroup >

CSS 變數

--AvatarGroup-gap

--Avatar-size

--Avatar-ringSize

結構

頭像元件由一個根 <div> 組成，它可能會包裝 <svg>、<img> 或字串

<div class="MuiAvatar-root">
  <!-- Avatar contents -->
</div>

API

請參閱以下文件，以取得此處提及之元件的所有可用 props 和類別的完整參考。

頭像

Playground

圖片回退