Merge pull request #70 from aaronmhl/refactor/avatar

feat(avatar): add avatar component
TDesignOteam · Jun 28, 2024 · af33296 · af33296
2 parents 89135dd + 89cdb63
commit af33296
Show file tree

Hide file tree

Showing 21 changed files with 708 additions and 0 deletions.
diff --git a/site/sidebar.config.ts b/site/sidebar.config.ts
@@ -124,6 +124,12 @@ export default [
     name: 'Data',
     type: 'component', // 组件文档
     children: [
+      {
+        title: 'Avatar 头像',
+        name: 'avatar',
+        path: '/components/avatar',
+        component: () => import('tdesign-web-components/avatar/README.md'),
+      },
       {
         title: 'Calendar 日历',
         name: 'calendar',

diff --git a/src/avatar/README.md b/src/avatar/README.md
@@ -0,0 +1,73 @@
+---
+title: Avatar 头像
+description: 用图标、图片、字符的形式展示用户或事物信息
+isComponent: true
+usage: { title: '', description: '' }
+spline: base
+---
+
+### 头像类型
+
+头像提供了 3 种不同类型的头像：图标头像、图片头像、字符头像
+{{ base }}
+
+### 头像形状
+
+头像默认支持两种形状：round、circle，用户也可自定义设置头像形状
+{{ shape }}
+
+### 头像大小
+
+头像默认支持三种大小：small、medium、large，用户可自定义设置大小
+{{ size }}
+
+### 字符头像大小自适应
+
+头像支持字符自适应，即字符长度过长时，头像可自动调整字符以便呈现完整内容
+{{ adjust }}
+
+### 组合头像
+
+组合头像展现
+{{ group }}
+
+### 组合头像偏移方向
+
+组合头像可控制层叠方向
+{{ group-cascading }}
+
+### 组合头像个数
+
+组合头像可设置最大展示个数，超过则隐藏显示
+{{ group-max }}
+
+## API
+
+### Avatar Props
+
+名称 | 类型 | 默认值 | 说明 | 必传
+-- | -- | -- | -- | --
+className | String | - | 类名 | N
+style | Object | - | 样式，TS 类型：`React.CSSProperties` | N
+alt | String | - | 头像替换文本，仅当图片加载失败时有效 | N
+children | TNode | - | 子元素内容，同 content。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/omi/blob/master/tdesign/desktop/src/common.ts) | N
+content | TNode | - | 子元素内容。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/omi/blob/master/tdesign/desktop/src/common.ts) | N
+hideOnLoadFailed | Boolean | false | 加载失败时隐藏图片 | N
+icon | TElement | - | 图标。TS 类型：`TNode`。[通用类型定义](https://github.com/Tencent/omi/blob/master/tdesign/desktop/src/common.ts) | N
+image | String | - | 图片地址 | N
+imageProps | Object | - | 透传至 Image 组件。TS 类型：`ImageProps`，[Image API Documents](./image?tab=api)。[详细类型定义](https://github.com/Tencent/omi/blob/master/tdesign/desktop/src/avatar/type.ts) | N
+shape | String | circle | 形状。可选项：circle/round。TS 类型：`ShapeEnum ` `type ShapeEnum = 'circle' \| 'round'`。[详细类型定义](https://github.com/Tencent/omi/blob/master/tdesign/desktop/src/avatar/type.ts) | N
+size | String | - | 尺寸，示例值：small/medium/large/24px/38px 等。优先级高于 AvatarGroup.size 。Avatar 单独存在时，默认值为 medium。如果父组件存在 AvatarGroup，默认值便由 AvatarGroup.size 决定 | N
+onError | Function |  | TS 类型：`(context: { e: ImageEvent }) => void`<br/>图片加载失败时触发 | N
+
+### AvatarGroup Props
+
+名称 | 类型 | 默认值 | 说明 | 必传
+-- | -- | -- | -- | --
+className | String | - | 类名 | N
+style | Object | - | 样式，TS 类型：`React.CSSProperties` | N
+cascading | String | 'right-up' | 图片之间的层叠关系，可选值：左侧图片在上和右侧图片在上。可选项：left-up/right-up。TS 类型：`CascadingValue` `type CascadingValue = 'left-up' \| 'right-up'`。[详细类型定义](https://github.com/Tencent/omi/blob/master/tdesign/desktop/src/avatar/type.ts) | N
+collapseAvatar | TNode | - | 头像数量超出时，会出现一个头像折叠元素。该元素内容可自定义。默认为 `+N`。示例：`+5`，`...`, `更多`。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/omi/blob/master/tdesign/desktop/src/common.ts) | N
+max | Number | - | 能够同时显示的最多头像数量 | N
+popupProps | Object | - | 头像右上角提示信息。TS 类型：`PopupProps`，[Popup API Documents](./popup?tab=api)。[详细类型定义](https://github.com/Tencent/omi/blob/master/tdesign/desktop/src/avatar/type.ts) | N
+size | String | - | 尺寸，示例值：small/medium/large/24px/38px 等。优先级低于 Avatar.size | N
diff --git a/src/avatar/_example/adjust.tsx b/src/avatar/_example/adjust.tsx
@@ -0,0 +1,18 @@
+import 'tdesign-web-components/avatar';
+import 'tdesign-web-components/space';
+
+import { Component } from 'omi';
+
+export default class Avatar extends Component {
+  static css = 't-avatar{}';
+
+  render() {
+    return (
+      <t-space>
+        <t-avatar style={{ marginRight: '40px' }}>王</t-avatar>
+        <t-avatar style={{ marginRight: '40px' }}>王亿</t-avatar>
+        <t-avatar style={{ marginRight: '40px' }}>王亿亿</t-avatar>
+      </t-space>
+    );
+  }
+}
diff --git a/src/avatar/_example/base.tsx b/src/avatar/_example/base.tsx
@@ -0,0 +1,25 @@
+import 'tdesign-web-components/image';
+import 'tdesign-web-components/avatar';
+import 'tdesign-web-components/space';
+import 'tdesign-web-components/icon';
+
+// import 'tdesign-icons-omi/user'
+import { Component } from 'omi';
+
+export default class Avatar extends Component {
+  static css = 't-avatar{}';
+
+  render() {
+    return (
+      <t-space>
+        <t-avatar icon={<t-icon name="user-1"></t-icon>} style={{ marginRight: '40px' }} />
+        <t-avatar
+          image="https://tdesign.gtimg.com/site/avatar.jpg"
+          hideOnLoadFailed={false}
+          style={{ marginRight: '40px' }}
+        />
+        <t-avatar style={{ marginRight: '40px' }}>W</t-avatar>
+      </t-space>
+    );
+  }
+}
diff --git a/src/avatar/_example/group-cascading.tsx b/src/avatar/_example/group-cascading.tsx
@@ -0,0 +1,28 @@
+import 'tdesign-web-components/avatar';
+import 'tdesign-web-components/space';
+import 'tdesign-web-components/avatar/avatar-group';
+import 'tdesign-web-components/icon';
+
+import { Component } from 'omi';
+
+export default class AvatarGroupCascading extends Component {
+  static css = 't-avatar{}';
+
+  render() {
+    return (
+      <t-space direction="vertical">
+        <t-avatar-group>
+          <t-avatar image="https://tdesign.gtimg.com/site/avatar.jpg"></t-avatar>
+          <t-avatar>W</t-avatar>
+          <t-avatar icon={<t-icon name="user-1"></t-icon>}></t-avatar>
+        </t-avatar-group>
+
+        <t-avatar-group cascading="left-up">
+          <t-avatar image="https://tdesign.gtimg.com/site/avatar.jpg"></t-avatar>
+          <t-avatar>W</t-avatar>
+          <t-avatar icon={<t-icon name="user-1"></t-icon>}></t-avatar>
+        </t-avatar-group>
+      </t-space>
+    );
+  }
+}
diff --git a/src/avatar/_example/group-max.tsx b/src/avatar/_example/group-max.tsx
@@ -0,0 +1,35 @@
+import 'tdesign-web-components/avatar';
+import 'tdesign-web-components/space';
+import 'tdesign-web-components/avatar/avatar-group';
+import 'tdesign-web-components/icon';
+import 'tdesign-web-components/image';
+
+import { Component } from 'omi';
+
+export default class AvatarGroupMax extends Component {
+  static css = 't-avatar{}';
+
+  render() {
+    return (
+      <t-space direction="vertical">
+        <t-avatar-group size="large" max={2}>
+          <t-avatar image="https://tdesign.gtimg.com/site/avatar.jpg"></t-avatar>
+          <t-avatar>Avatar</t-avatar>
+          <t-avatar image="https://tdesign.gtimg.com/site/avatar.jpg"></t-avatar>
+        </t-avatar-group>
+
+        <t-avatar-group size="large" max={2} collapseAvatar={<t-icon name="ellipsis" />}>
+          <t-avatar image="https://tdesign.gtimg.com/site/avatar.jpg"></t-avatar>
+          <t-avatar>Avatar</t-avatar>
+          <t-avatar icon={<t-icon name="user-1"></t-icon>}></t-avatar>
+        </t-avatar-group>
+
+        <t-avatar-group size="large" max={2} collapseAvatar="more">
+          <t-avatar image="https://tdesign.gtimg.com/site/avatar.jpg"></t-avatar>
+          <t-avatar>Avatar</t-avatar>
+          <t-avatar icon={<t-icon name="user-1"></t-icon>}></t-avatar>
+        </t-avatar-group>
+      </t-space>
+    );
+  }
+}
diff --git a/src/avatar/_example/group.tsx b/src/avatar/_example/group.tsx
@@ -0,0 +1,29 @@
+import 'tdesign-web-components/avatar';
+import 'tdesign-web-components/space';
+import 'tdesign-web-components/avatar/avatar-group';
+import 'tdesign-web-components/icon';
+
+// import 'tdesign-icons-omi/user'
+import { Component } from 'omi';
+
+export default class AvatarGroup extends Component {
+  static css = 't-avatar{}';
+
+  render() {
+    return (
+      <t-space direction="vertical">
+        <t-avatar-group>
+          <t-avatar image="https://tdesign.gtimg.com/site/avatar.jpg"></t-avatar>
+          <t-avatar>W</t-avatar>
+          <t-avatar icon={<t-icon name="user-1"></t-icon>}></t-avatar>
+        </t-avatar-group>
+
+        <t-avatar-group size="large">
+          <t-avatar image="https://tdesign.gtimg.com/site/avatar.jpg"></t-avatar>
+          <t-avatar>W</t-avatar>
+          <t-avatar icon={<t-icon name="user-1"></t-icon>}></t-avatar>
+        </t-avatar-group>
+      </t-space>
+    );
+  }
+}
diff --git a/src/avatar/_example/shape.tsx b/src/avatar/_example/shape.tsx
@@ -0,0 +1,17 @@
+import 'tdesign-web-components/avatar';
+import 'tdesign-web-components/space';
+
+import { Component } from 'omi';
+
+export default class AvatarShape extends Component {
+  render() {
+    return (
+      <t-space>
+        <t-avatar style={{ marginRight: '40px' }}>W</t-avatar>
+        <t-avatar shape="round" style={{ marginRight: '40px' }}>
+          W
+        </t-avatar>
+      </t-space>
+    );
+  }
+}
diff --git a/src/avatar/_example/size.tsx b/src/avatar/_example/size.tsx
@@ -0,0 +1,68 @@
+import 'tdesign-web-components/avatar';
+import 'tdesign-web-components/space';
+
+import { Component } from 'omi';
+
+export default class AvatarSize extends Component {
+  render() {
+    return (
+      <t-space direction="vertical" size="large">
+        <t-space align="center">
+          <t-avatar size="small" style={{ marginRight: '40px' }}>
+            W
+          </t-avatar>
+          <t-avatar size="medium" style={{ marginRight: '40px' }}>
+            W
+          </t-avatar>
+          <t-avatar size="large" style={{ marginRight: '40px' }}>
+            W
+          </t-avatar>
+          <t-avatar size="100px" style={{ marginRight: '40px' }}>
+            W
+          </t-avatar>
+        </t-space>
+        <t-space align="center">
+          <t-avatar shape="round" size="small" style={{ marginRight: '40px' }}>
+            W
+          </t-avatar>
+          <t-avatar shape="round" size="medium" style={{ marginRight: '40px' }}>
+            W
+          </t-avatar>
+          <t-avatar shape="round" size="large" style={{ marginRight: '40px' }}>
+            W
+          </t-avatar>
+          <t-avatar shape="round" size="100px" style={{ marginRight: '40px' }}>
+            W
+          </t-avatar>
+        </t-space>
+        <t-space align="center">
+          <t-avatar
+            alt="test"
+            image="https://tdesign.gtimg.com/site/avatar.jpg"
+            shape="round"
+            size="small"
+            style={{ marginRight: '40px' }}
+          ></t-avatar>
+          <t-avatar
+            image="https://tdesign.gtimg.com/site/avatar.jpg"
+            shape="round"
+            size="medium"
+            style={{ marginRight: '40px' }}
+          ></t-avatar>
+          <t-avatar
+            image="https://tdesign.gtimg.com/site/avatar.jpg"
+            shape="round"
+            size="large"
+            style={{ marginRight: '40px' }}
+          ></t-avatar>
+          <t-avatar
+            image="https://tdesign.gtimg.com/site/avatar.jpg"
+            shape="round"
+            size="100px"
+            style={{ marginRight: '40px' }}
+          ></t-avatar>
+        </t-space>
+      </t-space>
+    );
+  }
+}
diff --git a/src/avatar/avatar-group.tsx b/src/avatar/avatar-group.tsx
@@ -0,0 +1,84 @@
+import './avatar';
+
+import { toArray } from 'lodash';
+import { classNames, cloneElement, Component, OmiProps, tag } from 'omi';
+
+import { getClassPrefix } from '../_util/classname';
+import parseTNode from '../_util/parseTNode';
+import { StyledProps } from '../common';
+import { styleSheet } from './style/index.ts';
+import { TdAvatarGroupProps } from './type';
+
+import borderCss from './style/border.less';
+import offsetLeftCss from './style/offset_left.less';
+import offsetLeftZIndexCss from './style/offset_left_zIndex.less';
+import offsetRightCss from './style/offset_right.less';
+
+export interface AvatarGroupProps extends TdAvatarGroupProps, StyledProps {}
+
+@tag('t-avatar-group')
+export default class AvatarGroup extends Component<AvatarGroupProps> {
+  static css = styleSheet;
+
+  static defaultProps = { cascading: 'right-up' };
+
+  static propTypes = {
+    cascading: String,
+    max: Number,
+    size: String,
+    collapseAvatar: Object,
+    children: Object,
+  };
+
+  preClass = `${getClassPrefix()}-avatar`;
+
+  allChildrenList: any;
+
+  provide = { groupSize: undefined as any };
+
+  install() {
+    this.provide = { groupSize: this.props.size };
+  }
+
+  render(props: OmiProps<AvatarGroupProps, any>) {
+    const { preClass } = this;
+    const { children, max, cascading, collapseAvatar } = props;
+    const childrenList = toArray(children);
+    if (childrenList.length > 0) {
+      this.allChildrenList = childrenList.map((child, index) => {
+        let childrenCss = borderCss;
+        if (cascading === 'right-up' && index !== childrenList.length - 1) {
+          childrenCss += offsetRightCss;
+        } else if (cascading === 'left-up' && index !== 0) {
+          childrenCss += offsetLeftCss + offsetLeftZIndexCss;
+        } else if (cascading === 'left-up') {
+          childrenCss += offsetLeftZIndexCss;
+        }
+
+        return cloneElement(child, {
+          key: `avatar-group-item-${index}`,
+          css: childrenCss,
+        });
+      });
+    }
+    const groupClass = classNames(`${preClass}-group`, this.className, {
+      [`${preClass}--offset-right`]: cascading === 'right-up',
+      [`${preClass}--offset-left`]: cascading === 'left-up',
+    });
+
+    const childrenCount = childrenList.length;
+    if (props.max && childrenCount > max) {
+      const showList = this.allChildrenList.slice(0, max);
+      let childrenCss = borderCss;
+      if (cascading === 'left-up') {
+        childrenCss += offsetLeftCss + offsetLeftZIndexCss;
+      }
+      const ellipsisAvatar = (
+        <t-avatar css={childrenCss}>{parseTNode(collapseAvatar) || `+${childrenCount - max}`} </t-avatar>
+      );
+      showList.push(<div key="t-avatar__collapse">{ellipsisAvatar}</div>);
+      return <div class={groupClass}>{showList}</div>;
+    }
+    return <div class={groupClass}>{this.allChildrenList}</div>;
+  }
+}