# Avatar 头像

- 来源：[E10 UI 组件库](https://www.e-cology.com.cn/ui/avatar/freepass)
- 平台：PC
- 维护者：陈佳敏
- 设计稿：http://pd.e-cology.com.cn/pd/E10/interface/e10xiaoguotu/PC/E10zjys/#s33
- Issue：http://gitlab.ecology10.cn/FRONTEND/weapp-ui/-/issues?state=all&search=[Avatar]

## 代码演示

### 个人头像

展示不同的头像配置效果（图片显示、默认性别、姓名首字母、姓名后两字、固定图片的裁剪/拉伸/填充模式）

```jsx
import { Component } from 'react';
import { Avatar, constants } from '@weapp/ui';

import AvatarImage1 from '../images/avatar_demo_1.jpeg';
import AvatarImage2 from '../images/avatar_demo_2.jpg';

const prefixCls = `${constants.uiPcClsPrefix}-demo-avatar`;

// avatarConfigList 配置：展示不同的头像效果
const avatarConfigList = [
  // 1. 图片显示
  {
    description: '图片显示',
    url: AvatarImage1,
  },
  // 2. 默认性别展示 - 男
  {
    description: '默认性别 - 男',
    gender: 'male' as const,
  },
  // 3. 默认性别展示 - 女
  {
    description: '默认性别 - 女',
    gender: 'female' as const,
  },
  // 4. 默认姓名首字母 - 中文
  {
    description: '默认姓名首字母(女) - 中文',
    name: '王晓晓 (南京)',
    gender: 'female' as const,
    defaultAvatarConfig: {
      avatarType: 'surName' as const,
      avatarFemaleFontColor: '#FFF',
      avatarFemaleBgColor: '#EF8BBA',
    }
  },
  // 5. 默认姓名首字母 - 英文
  {
    description: '默认姓名首字母(男) - 英文',
    name: 'Harry James Potter',
    gender: 'male' as const,
    defaultAvatarConfig: {
      avatarType: 'surName' as const,
      avatarMaleFontColor: '#FFF',
      avatarMaleBgColor: '#5D9CEC',
    }
  },
  // 6. 默认姓名后两字 - 中文
  {
    description: '默认姓名后两字(女) - 中文',
    name: '王晓晓（上海）',
    gender: 'female' as const,
    defaultAvatarConfig: {
      avatarType: 'shortName' as const,
      avatarFemaleFontColor: '#FFF',
      avatarFemaleBgColor: '#EF8BBA',
    }
  },
  // 7. 默认姓名后两字 - 英文
  {
    description: '默认姓名后两字(男) - 英文',
    name: 'Harry James Potter',
    gender: 'male' as const,
    defaultAvatarConfig: {
      avatarType: 'shortName' as const,
      avatarMaleFontColor: '#FFF',
      avatarMaleBgColor: '#5D9CEC',
    }
  },
  // 8. 默认固定图片 - 裁剪模式
  {
    description: '默认固定图片 - 裁剪模式',
    gender: 'female' as const,
    defaultAvatarConfig: {
      avatarType: 'image' as const,
      avatarFemaleImage: AvatarImage2,
      avatarImageEffect: 'crop' as const,
    }
  },
  // 9. 默认固定图片 - 拉伸模式
  {
    description: '默认固定图片 - 拉伸模式',
    gender: 'female' as const,
    defaultAvatarConfig: {
      avatarType: 'image' as const,
      avatarFemaleImage: AvatarImage2,
      avatarImageEffect: 'stretch' as const,
    }
  },
  // 10. 默认固定图片 - 原比例底色填充模式
  {
    description: '默认固定图片 - 原比例填充模式',
    gender: 'female' as const,
    defaultAvatarConfig: {
      avatarType: 'image' as const,
      avatarFemaleImage: AvatarImage2,
      avatarImageEffect: 'fill' as const,
      avatarImageBorderColor: '#D7D7D7',
      avatarImageBgColor: '#FFFFFF',
    }
  },
];

class AvatarDemo extends Component {
  render() {
    return (
      <div className={prefixCls}>
        <div className={`${prefixCls}-grid`}>
          {avatarConfigList.map((config, index) => (
            <div key={index} className={`${prefixCls}-item`}>
              <div className={`${prefixCls}-item-label`}>{config.description}</div>
              <div className={`${prefixCls}-item-content`}>
                <Avatar
                 
                  size="lg"
                  shape="circle"
                  {...config}
                />
              </div>
            </div>
          ))}
        </div>
      </div>
    );
  }
}

export default AvatarDemo;
```

### 不同尺寸

size 属性设置尺寸（lg、md、sm、xs）

```jsx
import { Component } from 'react';
import { Avatar, Icon, constants } from '@weapp/ui';

import AvatarImage1 from '../images/avatar_demo_1.jpeg';

const prefixCls = `${constants.uiPcClsPrefix}-demo-avatar`;
const sizes = ['lg', 'md', 'sm', 'xs'] as const;

class AvatarDemo extends Component {
  render() {
    return (
      <div className={prefixCls}>
        <div className={`${prefixCls}-flex`}>
          {sizes.map(size => (
            <div key={size} className={`${prefixCls}-item`}>
              <div className={`${prefixCls}-item-label`}>{size.toUpperCase()}</div>
              <div className={`${prefixCls}-item-content`}>
                <Avatar size={size} url={AvatarImage1} name={'沈隽磊'} gender="female" />
              </div>
            </div>
          ))}
        </div>
      </div>
    );
  }
}

export default AvatarDemo;
```

### 不同形状

shape 属性设置形状（circle、square）

```jsx
import { Component } from 'react';
import { Avatar, constants } from '@weapp/ui';

import AvatarImage1 from '../images/avatar_demo_1.jpeg';

const prefixCls = `${constants.uiPcClsPrefix}-demo-avatar`;

class AvatarDemo extends Component {
  render() {
    return (
      <div className={prefixCls}>
        <div className={`${prefixCls}-flex`}>
          <div className={`${prefixCls}-item`}>
            <div className={`${prefixCls}-item-label`}>圆形</div>
            <div className={`${prefixCls}-item-content`}>
              <Avatar size='lg' shape='circle' url={AvatarImage1} name={'沈隽磊'} gender="female" />
            </div>
          </div>
          <div className={`${prefixCls}-item`}>
            <div className={`${prefixCls}-item-label`}>方形</div>
            <div className={`${prefixCls}-item-content`}>
              <Avatar size='lg' shape='square' url={AvatarImage1} name={'沈隽磊'} gender="female" />
            </div>
          </div>
        </div>
      </div>
    );
  }
}

export default AvatarDemo;
```

### 不同状态

status 属性设置状态（onlie、offline）

```jsx
import { Component } from "react";
import { Avatar, constants } from "@weapp/ui";

import AvatarImage1 from '../images/avatar_demo_1.jpeg';

const prefixCls = `${constants.uiPcClsPrefix}-demo-avatar`;

class AvatarDemo extends Component {
  render() {
    return (
      <div className={prefixCls}>
        <div className={`${prefixCls}-flex`}>
          <div className={`${prefixCls}-item`}>
            <div className={`${prefixCls}-item-label`}>
              在线状态（自定义图标）
            </div>
            <div className={`${prefixCls}-item-content`}>
              <Avatar
               
                size="lg"
                shape="circle"
                url={AvatarImage1}
                status="online"
                statusIcon="Icon-PC-online-blue-mcolor"
              />
            </div>
          </div>

          <div className={`${prefixCls}-item`}>
            <div className={`${prefixCls}-item-label`}>离线状态（0.7蒙层）</div>
            <div className={`${prefixCls}-item-content`}>
              <Avatar
               
                size="lg"
                shape="circle"
                url={AvatarImage1}
                status="offline"
              />
            </div>
          </div>
        </div>
      </div>
    );
  }
}

export default AvatarDemo;
```

### 群组、匿名

显示默认的群组或者匿名头像 (isGroup、anonymous )

```jsx
import { Component } from 'react';
import { Avatar, constants } from '@weapp/ui';

const prefixCls = `${constants.uiPcClsPrefix}-demo-avatar`;

class AvatarDemo extends Component {
  render() {
    return (
      <div className={prefixCls}>
        <div className={`${prefixCls}-flex`}>
          <div className={`${prefixCls}-item`}>
            <div className={`${prefixCls}-item-label`}>群组</div>
            <div className={`${prefixCls}-item-content`}>
              <Avatar isGroup />
            </div>
          </div>
          <div className={`${prefixCls}-item`}>
            <div className={`${prefixCls}-item-label`}>匿名</div>
            <div className={`${prefixCls}-item-content`}>
              <Avatar anonymous />
            </div>
          </div>
        </div>
      </div>
    );
  }
}

export default AvatarDemo;
```

### 自定义渲染

使用customRender api

```jsx
import { Component } from 'react';
import { Avatar, constants } from '@weapp/ui';

const prefixCls = `${constants.uiPcClsPrefix}-demo-avatar`;

class AvatarDemo extends Component {
  customRenderAvatar = () => {
    return <span>自定义头像显示</span>
  }

  render() {
    return (
      <div className={prefixCls}>
        <h3>自定义渲染</h3>
        <Avatar customRender={this.customRenderAvatar} />
      </div>
    );
  }
}

export default AvatarDemo;
```

## API

```
Tip: 
1、人员头像默认的头像 统一读取系统的 通用设置 --> 系统默认头像设置 中的配置
2、如果尺寸为sm|xs，头像加载失败后，都会显示为固定的图片效果
```

### 参数说明如下：

| 参数 | 说明 | 类型 | 是否必填 | 默认值 |
| --- | --- | --- | --- | --- |
| url | 图片地址 | string | 人员\|群组头像必填 | - |
| name | 姓名 | string | 人员头像必填 | - |
| gender | 性别 | 'male' \| 'female' | 否 | 'male' |
| isGroup | 是否为群组头像 | boolean | 否 | false |
| anonymous | 是否匿名 | boolean | 否 | false |
| size | 尺寸 | 'lg' \| 'md' \| 'sm' \| 'xs' | 否 | 'lg' |
| shape | 形状 | 'circle' \| 'square' | 否 | 'circle' |
| status | 状态 | 'online' \| 'offline' | 否 | - |
| statusIcon | 在线状态图标 | IconName \| ReactNode | 否 | - |
| imgFormat | 请求头像图片尺寸,small表示压缩后的图片,请求速度回更快,image表示原图 | 'small' \| 'big' \| 'image' | 否 | 'small' |
| className | class 名 | string | 否 | - |
| prefixCls | 默认组件 class 名 | string | 否 | - |
| style | 样式 | CSSProperties | 否 | - |
| loginFree | 是否为免登场景 | boolean | 否 | false |
| customRender | 自定义组件渲染 | (props: any, ele: ReactElement) => ReactElement | 否 | - |
| defaultAvatarConfig | 自定义头像的默认配置（不从统一的配置中读取,但是属性需要按照统一的属性） | object | 否 | - |
| onClick | 自定义头像点击事件 | (userId?: string) => void | 否 | - |
| inHrmCard | 是否在人力卡片中使用（处理ie浏览器图片自适应问题） | boolean | 否 | false |
| avatarIconProps | 图标属性 | IconProps | 否 | - |
| useAnonymous | 强制使用匿名展示 | boolean | 否 | false |
### defaultAvatarConfig 配置说明：

| 参数 | 说明 | 类型 | 是否必填 | 默认值 |
| --- | --- | --- | --- | --- |
| avatarType | 默认头像格式 | 'surName' \| 'shortName' \| 'image' | 否 | 'surName' |
| avatarFemaleFontColor | 女性头像文字颜色（avatarType为姓名相关时生效） | string | 否 | '#FFF' |
| avatarFemaleBgColor | 女性头像背景颜色（avatarType为姓名相关时生效） | string | 否 | '#EF8BBA' |
| avatarFemaleImage | 女性头像默认图片 | string | 否 | - |
| avatarMaleImage | 男性头像默认图片 | string | 否 | - |
| avatarMaleFontColor | 男性头像文字颜色（avatarType为姓名相关时生效） | string | 否 | '#FFF' |
| avatarMaleBgColor | 男性头像背景颜色（avatarType为姓名相关时生效） | string | 否 | '#5D9CEC' |
| avatarImageEffect | 图片头像效果 | 'crop' \| 'stretch' \| 'fill' | 否 | 'crop' |
| avatarImageBorderColor | 边框色（仅在 avatarImageEffect='fill' 时生效） | string | 否 | '#D7D7D7' |
| avatarImageBgColor | 背景色（仅在 avatarImageEffect='fill' 时生效） | string | 否 | '#FFF' |
**avatarType 说明：**

- `surName`: 姓名首字
- `shortName`: 姓名后两字（会自动过滤括号中的备注内容，如"王晓晓 (南京)"会显示为"晓晓"）
- `image`: 固定图片

**avatarImageEffect 说明：**

- `crop`: 裁剪模式，1:1比例，填充整个容器（object-fit: cover）
- `stretch`: 拉伸模式，不管原始图片宽高，统一宽高100%显示（object-fit: fill）
- `fill`: 原比例填充模式，保持原始比例，完整显示，支持设置边框色和背景色（object-fit: contain）
