Группа аватаров

Обзор

AvatarGroup получает отрисованные аватары и определяет количество скрытых. maxVisible учитывает фактические аватары; индикатор переполнения является дополнительным. При наличии восьми аватаров maxVisible={3} отображаются три аватара и +5.

Использование

import { AvatarGroup } from 'twenty-ui/components/data-display';
import { Avatar } from 'twenty-ui/primitives/data-display';

export const TeamAvatars = () => (
  <AvatarGroup
    maxVisible={3}
    overflowShape="circle"
    overlap="left"
    overlapOffset="4px"
    avatars={[
      'Ada',
      'Grace',
      'Margaret',
      'Annie',
      'Mary',
      'Dorothy',
      'Katherine',
      'Joan',
    ].map((name) => (
      <Avatar
        key={name}
        name={name}
        shape="circle"
        imageProps={{ alt: name }}
      />
    ))}
  />
);

Передавайте стабильные ключи, чтобы оставшиеся аватары оставались смонтированными при изменении лимита, общего количества или порядка отображения. Аватары по умолчанию являются декоративными. Когда группа является единственным представлением своих участников, укажите имя каждого участника через imageProps.alt, чтобы добавить подпись к изображению и резервному варианту по умолчанию. Сохраняйте аватары декоративными, когда видимый текст или метка владельца уже указывают на эту личность.

Визуальные параметры

Сравните круглые и квадратные аватары каждого размера. В этой сравнительной таблице в группе отображаются три участника.

Частично загруженные коллекции

Используйте total для полного размера коллекции, когда загружены только некоторые аватары. Три переданных и видимых аватара с total={20} отображают +17. Передайте все загруженные аватары и позвольте группе применить maxVisible.

import { AvatarGroup } from 'twenty-ui/components/data-display';
import { Avatar } from 'twenty-ui/primitives/data-display';

export const LoadedTeamAvatars = () => (
  <AvatarGroup
    maxVisible={3}
    total={20}
    avatars={['Ada', 'Grace', 'Margaret'].map((name) => (
      <Avatar key={name} name={name} imageProps={{ alt: name }} />
    ))}
  />
);

Значение total округляется вниз и не может быть меньше количества переданных аватаров, пригодных для рендеринга. Для неконечных итоговых значений используется переданное количество. Вычисленное количество скрытых аватаров всегда неотрицательно. Значение maxVisible по умолчанию равно 4. Конечные лимиты округляются вниз и ограничиваются нулём, Infinity отображает все переданные аватары, а NaN не отображает ни одного. Пустые узлы React не считаются аватарами. При нулевом лимите может отображаться только индикатор переполнения. Пустая группа с положительным общим количеством может показывать это количество в своём индикаторе; пустая группа без скрытых аватаров ничего не рендерит.

Пользовательское переполнение

renderOverflow получает то же вычисленное количество скрытых аватаров, что и стандартный индикатор +N. Он выполняется только при положительном количестве. Верните null, чтобы скрыть индикатор, не изменяя набор видимых аватаров. Используйте явный элемент управления, когда индикатор выполняет действие. Его доступное имя должно описывать действие и количество.

import { AvatarGroup } from 'twenty-ui/components/data-display';
import { Avatar } from 'twenty-ui/primitives/data-display';
import { Button } from 'twenty-ui/primitives/input';

type TeamAvatarsWithActionProps = { onShowAll: () => void };

export const TeamAvatarsWithAction = ({
  onShowAll,
}: TeamAvatarsWithActionProps) => (
  <AvatarGroup
    maxVisible={3}
    total={20}
    avatars={['Ada', 'Grace', 'Margaret'].map((name) => (
      <Avatar key={name} name={name} imageProps={{ alt: name }} />
    ))}
    renderOverflow={(hiddenCount) => (
      <Button
        size="sm"
        aria-label={`Show ${hiddenCount} more members`}
        onClick={onShowAll}
      >
        +{hiddenCount}
      </Button>
    )}
  />
);

Внешний вид

Более поздние аватары всегда отрисовываются поверх более ранних. overlap выбирает физическое поле, left или right, к которому применяется отрицательное смещение. overlapOffset задаёт это смещение как длину CSS. overflowShape задаёт форму стандартного числового индикатора.

Настройка корневого элемента

Нативные атрибуты, обработчики событий, className и style применяются к корневому элементу. Его элементом по умолчанию является div, в том числе при передаче onClick. Используйте нативные интерактивные элементы для действий, например кнопку переполнения выше. Корневой элемент принимает ref и render, который может быть элементом или функцией. Пользовательские компоненты должны передавать предоставленные props и ref своему нативному корневому элементу. См. пользовательские компоненты, чтобы ознакомиться с требованиями к композиции.

import { useRef } from 'react';
import { AvatarGroup } from 'twenty-ui/components/data-display';
import { Avatar } from 'twenty-ui/primitives/data-display';

export const NamedTeamAvatars = () => {
  const groupRef = useRef<HTMLDivElement>(null);

  return (
    <AvatarGroup
      ref={groupRef}
      role="group"
      aria-label="Project members"
      style={{ marginBlock: 8 }}
      render={<div data-location="project-header" />}
      avatars={['Ada', 'Grace', 'Margaret'].map((name) => (
        <Avatar key={name} name={name} imageProps={{ alt: name }} />
      ))}
    />
  );
};

Свойства

AvatarGroupProps экспортируется из twenty-ui/components/data-display.

ReactNode[]

обязательно

Avatar elements in display order. Empty React nodes are ignored. Supply stable keys to preserve identity when reordering.

string

Class applied to the group container.

number

по умолчанию:"4"

Maximum number of actual avatars to show, excluding the overflow indicator. Floored and clamped to zero; Infinity shows all avatars and NaN shows none.

"circle" | "rounded-square" | "square"

по умолчанию:"square"

Shape of the numeric overflow indicator.

"left" | "right"

по умолчанию:"right"

Physical margin, left or right, that carries the negative overlap offset. Later avatars always render above earlier ones.

string

по умолчанию:"3px"

CSS length of the overlap between avatars.

Ref<HTMLDivElement>

Ref to the rendered root element.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Element or render function for the root. Forward the supplied props and ref; the default element is a div.

((hiddenCount: number) => ReactNode)

Called with the derived hidden count when it is positive. Return a custom indicator, or null to hide it.

number

Total collection size for partially loaded avatars. Floored and never smaller than the supplied renderable count; nonfinite values use the supplied count.

Разработчики

Приложения

API

Самостоятельный хостинг

Внести вклад

Библиотека интерфейса

Обзор

Использование

Визуальные параметры

Частично загруженные коллекции

Пользовательское переполнение

Внешний вид

Настройка корневого элемента

Свойства

​Обзор

​Использование

​Визуальные параметры

​Частично загруженные коллекции

​Пользовательское переполнение

​Внешний вид

​Настройка корневого элемента

​Свойства

Обзор

Использование

Визуальные параметры

Частично загруженные коллекции

Пользовательское переполнение

Внешний вид

Настройка корневого элемента

Свойства