Дизайн компонентов

Информацию о том, как разрабатывать компоненты, см. в документации по разработке компонентов component-development.

Мы используем ряд шаблонов и соглашений во всех наших компонентах.

Перечисления размеров

Для обозначения размеров мы используем аббревиатуры, например, xxl, xl, l, m, s, xs и xxs.

Перечисления и карты

Мы определяем объекты, которые сопоставляют перечисления с соответствующими значениями, обычно классами CSS. Например, вот как мы определили бы карты для цветов и размеров в вымышленном компоненте MegaMenu.

// Сначала мы определяем значения перечисления как тип
type EuiMegaMenuColor = 'primary' | 'secondary' | 'warning' | 'danger';

// Затем мы определяем карту для получения соответствующего класса для каждого значения перечисления.
const colorToClassNameMap: { [color in EuiMegaMenuColor]: string } = {
  primary: 'euiMegaMenu--primary',
  secondary: 'euiMegaMenu--secondary',
  warning: 'euiMegaMenu--warning',
  danger: 'euiMegaMenu--danger',
};

// Затем мы генерируем сами перечисления, извлекая ключи.
export const COLORS = keysOf(colorToClassNameMap);

Вот как мы определяем типы свойств с использованием сгенерированных перечислений в Typescript:

// Мы можем ссылаться на объекты перечислений для типов свойств.
export type EuiMegaMenuProps = {
  color: EuiMegaMenuColor;
  isDisabled?: boolean;
  /* ... */
};

Для свойств по умолчанию мы можем просто указать значения перечисления, которые хотим использовать, в конструкторе, а затем использовать карты для генерации className для компонента:

export const EuiMegaMenu: FunctionComponent<EuiMegaMenuProps> = ({
  children,
  className,
  color = 'primary',
  className,
  isDisabled = false,
  ...rest
}) => {
  const classes = classNames(
    'euiMegaMenu',
    colorToClassNameMap[color],
    className,
    {
      'euiMegaMenu--isDisabled': isDisabled,
    },
  );

  /* ... */
}

Проходные свойства

Чтобы предоставить потребителю как можно больше гибкости, мы используем деструктурирующее присваивание для извлечения ожидаемых свойств из полученных свойств и передаём ...rest одному из элементов в методе render(). Этим элементом обычно является корневой элемент, хотя в редких случаях другой элемент имеет больше смысла.

Основное преимущество этой практики заключается в том, что потребитель может указать любой из атрибутов DOM, поддерживаемых React, включая пользовательские с префиксом data-.

В Typescript имеет смысл расширить свойства этого элемента при объявлении типа компонента. EUI также предоставляет краткий список часто используемых свойств, таких как className, aria-label и data-test-subj, которые вы также должны расширить.

import { HTMLAttributes, FunctionComponent } from 'react';
import { CommonProps } from '../common';

export type EuiMegaMenuProps = HTMLAttributes<HTMLDivElement> &
  CommonProps & {
    color: EuiMegaMenuColor;
    isDisabled?: boolean;
    /* ... */
  };

export const EuiMegaMenu: FunctionComponent<EuiMegaMenuProps> = ({
  children,
  className,
  color = 'primary',
  size,
  className,
  isDisabled = false,
  ...rest
}) => {

  // Всё остальное, указанное потребителем, будет применено к div как атрибут DOM.
  return (
    <div {...rest}>
      {/* ... */}
    </div>
  );
}

Именование свойств

Перечисления

Строковые литералы следует использовать везде, где это возможно, и отдавать им приоритет перед логическими значениями. Это обеспечивает максимальную расширяемость при добавлении новых функций/опций в будущем. Например, вместо свойства isHorizontal: boolean используйте layout: 'horizontal' | 'vertical'.

Логические значения

Как правило, логические свойства должны иметь префикс is, например, isPlaceholder или isReadOnly. Исключением является случай, когда свойство соответствует существующему атрибуту HTML, такому как disabled; чтобы избежать путаницы, имя свойства должно соответствовать спецификации HTML. Такое соответствие имеет наибольший смысл, когда компонент представляет собой тонкую оболочку существующего элемента HTML, например, EuiButton -> <button> и EuiRadio -> <input type="radio">.

Обработчики событий

Все обработчики событий должны принимать форму onEvent и точно описывать, когда они будут called. Например, onClick указывает на то, что обработчик вызывается при клике на компонент, но если нужна большая детализация, то обработчику следует отразить это через onItemClick, onRowClick и т. д.

Common and required props

Старайтесь использовать проп children везде, где это возможно. Это создаст более простой и единообразный API для всех наших компонентов.

Также мы требуем поддержки некоторых пропов всеми компонентами, как отражено в наших тестах; например, className. Их легко добавить через упомянутый выше CommonProps.