[Перевод] Десять заповедей React компонентов19.07.2019 22:18

the-10-component-commandments

Написано Kristofer Selbekk, в сотрудничестве с Caroline Odden. Основано на лекции с таким же названием и с теми же людьми, состоявшейся на встрече ReactJS в Осло в июне 2019 года.

От переводчика — оригинальное название The 10 Component Commandments не упоминает React, но большинство примеров и рекомендаций относятся именно к реакту, к тому же статья выложена под react тэгом и написана реакт разработчиками.

Не легко создавать компоненты которыми будут пользоваться многие разработчики. Вы должны очень тщательно продумать какие пропсы использовать, если эти пропсы будут частью общедоступного API.

В этой статье мы сделаем краткое введение в некоторые лучшие практики по разработке API в целом, а также сформируем десять полезных заповедей, применяя которые вы сможете создавать компоненты, которыми ваши коллеги-разработчики будут рады пользоваться.

api

Что такое API?

API — или программный интерфейс приложения — место где встречаются два куска кода. Это контактная поверхность между вашим кодом и остальным миром. Мы называем эту поверхность интерфейсом. Это определенный набор действий или точек данных с которыми можно взаимодействовать.

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

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

Некоторые лучшие практики проектирования API

Итак, какие правила и соображения применяются при разработке API? Что ж, мы провели небольшое исследование, и оказалось что есть много отличных ресурсов на эту тему. Мы выбрали два — Josh Tauberer — «What makes a good API?» и статья Ron Kurir с тем же названием — и пришли к этим четырем практикам.

Стабильные версии

Одна из самых важных вещей, которую следует учитывать при создании API — это поддерживать его как можно более стабильным. Количество критических изменений должно быть минимальным. Если вам приходиться делать критические изменения, обязательно напишите подробные руководства по обновлению и, если возможно, напишите код-мод, который автоматизирует этот процесс для разработчиков.

Описательные сообщения об ошибках

Всегда когда возникает ошибка при вызове вашего API, нужно сделать все возможное чтобы объяснить что пошло не так и как это исправить. Если вы будите ругать пользователя сообщениями вроде «неправильное использование» и не давать каких либо пояснений, ваш API оставит плохое впечатление.

Вместо этого пишите описательные ошибки, которые помогут пользователю исправить то как они используют ваш API.

Минимизировать сюрпризы для разработчиков

Разработчики хрупкие существа, и вам не стоит их пугать когда они используют ваш API. Другими словами — сделайте ваш API как можно более интуитивным. Вы достигните этого если будите следовать лучшим практикам и существующим соглашениям об именах.

Так же, ваш код всегда должен быть последовательным. Если вы используете логические имена свойств с is или has в одном месте, но пропускаете их дальше — это будет сбивать людей с толку.

Минимизировать поверхность API

Ваш API то же нужно минимизировать. Множество возможностей это замечательно, но чем меньше поверхность вашего API (API surface), тем меньше разработчикам придется изучать его для того что бы начать продуктивно с ним работать. Благодаря этому ваш API будет восприниматься как простой в использовании!

Всегда есть способ проконтролировать размер ваших API. Один из них — рефакторинг нового API из старого.

Десять заповедей для веб компонентов

The 10 Component Commandments

Итак, эти четыре золотых правила хорошо работают для REST API и для старых процедурных штук на Pascal —, но как перенести их в современный мир React-а?

Как мы и говорили ранее, у компонентов есть свой API. Мы называем их props, и именно с их помощью данные передаются в компоненты. Как нам структурировать пропсы таким образом, чтобы не нарушать ни одно из приведенных выше правил?

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

1. Документируйте использование компонентов

Если то как нужно использовать ваш компонент не задокументировано, то этот компонент бесполезен. Ну, почти бесполезен, всегда можно посмотреть на его реализацию, но мало кто любит это делать.

Есть много способов задокументировать ваши компоненты, но мы рекомендуем обратить внимание на эти три:

Первые два дают вам площадку для работы при разработке ваших компонентов, а третье позволяет писать документацию в свободной форме при помощи MDX

Независимо от того что вы выберите, всегда документируйте как сам API, так и то как и когда ваши компоненты должны использоваться. Последняя часть критически важна в библиотеках общего назначения — что бы люди правильно использовали кнопку или сетку макета (layout grid) в заданном контексте.

2. Разрешите контекстную семантику

HTML — это язык для структурирования информации семантическим способом. Только вот большинство наших компонентов состоит из

тегов. В этом есть смысл — универсальные компоненты не могут знать заранее чем они будут, может

, или

—, но такая ситуация далека от идеала.

Существует иной вариант, просто позвольте вашим компонентам принимать проп as, и тем самым определять какой элемент DOM будет рендерится. Вот пример как можно это реализовать:

function Grid({ as: Element, ...props }) {
  return 
}
Grid.defaultProps = {
  as: 'div',
};

Мы переименовываем проп as в переменную Element и используем ее в нашем JSX. Мы даем общее значение div по умолчанию, если у нас нет более семантического HTML-тега для передачи.

Когда придет время использовать компонент , вы можете просто передать правильный тег:

function App() {
  return (
    
      
    
  );
}

Это работает и с React компонентами. К примеру, если вы хотите что бы компонент

3. Избегайте логических (boolean) пропсов

Логические пропсы — это же, вроде бы, хорошая идея. Их можно использовать без значения, так что выглядит это очень элегантно:

Но хоть это и выглядят симпатично, логические свойства допускают только две возможности. Вкл или выкл. Видимый или скрытый. 1 или 0.

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

Другими словами, логические свойства часто не масштабируются с изменением требований. Вместо них для значений, которые могут стать чем-то иным, кроме двоичного выбора, лучше используйте перечисляемые значения, такие как строки.

Это не значит что вообще нельзя использовать логические свойства. Можно! Проп disabled (выключенный), который я перечислял выше, все еще должен быть логическим — потому что нет никакого среднего состояния между включенным и выключенным. Просто оставьте логические свойства только для действительно бинарного выбора.

4. Используйте `props.children`

У React есть несколько специальных свойств, которые рассматриваются не так, как другие. Один из таких key, нужный для отслеживания порядка элементов списка. И еще один такой специальный проп это children.

Все, что вы помещаете между открывающим и закрывающим тегом компонента, помещается внутри пропа props.children. И вы должны использовать это как можно чаще.

Почему? Потому что это куда проще чем иметь проп content для контента или что-то подобное, что обычно принимает только простые значения, такие как текст.



// против

Some text

Есть несколько преимуществ использования props.children. Во-первых, это похоже на то как работает обычный HTML. Во-вторых, вы можете свободно передавать все что захотите! Вместо того чтобы добавлять пропсы вроде leftIcon и rightIcon в ваш компонент — просто передайте их как часть пропа props.children:


   Some text

Вы можете возразить что вашему компоненту нужно рендерить только обычный текст, и в некоторых случаях это так и есть. До какого-то момента. Используя же props.children, вы гарантируете что ваш API будет готов к меняющимся требованиям.

5. Позвольте родителю цепляться за внутреннюю логику

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

Такие компоненты часто страдают от чрезмерных API, одной из причин этого является большое количество различных вариантов использования которые накапливаются с развитием проекта.

А что если бы мы могли просто предоставить единый, стандартизированный проп, который позволить разработчику контролировать, реагировать на, или просто менять дефолтное поведение компонента?

Кент Доддс написал отличную статью о концепции state reducers. Вот статья о самой концепции, а также, вот статья о том как реализовать это для React хуков.

Вкратце, это паттерн передачи функции «state reducer» вашему компоненту, который позволит разработчику получить доступ ко всем действиям, выполняемым внутри вашего компонента. Вы можете изменить состояние (state) или даже вызывать побочные эффекты. Это отличный способ обеспечить высокий уровень кастомизации, безо всяких пропсов.

Вот как это может выглядеть:

function MyCustomDropdown(props) {
  const stateReducer = (state, action) => {
    if (action.type === Dropdown.actions.CLOSE) {
      buttonRef.current.focus();
    }
  };
  return (
    <>
      
      
    
}

Кстати, вы можете создать более простые способы реагирования на события (events). Использование пропа onClose в предыдущем примере, вероятно, сделает использование компонента удобнее. Используйте «state reducer» паттерн когда это нужно.

6. Используйте оператор троеточие (spread) для оставшихся пропсов

Каждый раз когда вы создаете новый компонент — убедитесь, что вы применили троеточие к оставшимся пропсам и отправили их в элемент для которого это имеет смысл.

Вам не нужно продолжать добавлять пропсы в ваш компонент, которые просто будут переданы базовому компоненту или элементу. Это сделает ваш API более стабильным, устраняя необходимость во множестве мелких ошибок версий, когда следующему разработчику требуется новый слушатель событий (event listener) или ARIA тег.

Вы можете сделать это так:

function ToolTip({ isVisible, ...rest }) {
  return isVisible ?  : null;
}

Всякий раз, когда ваш компонент передает проп в вашу реализацию, например, имя класса или обработчик onClick, убедитесь, что другой разработчик сможет сделать то же самое. В случае с классом вы можете просто добавить класс prop с помощью удобной npm библиотеки classnames (или просто конкатенацией строк):

import classNames from 'classnames';
function ToolTip(props) {
  return (
    
}

В случае с обработчиками кликов (click handlers) и с другими колбеками вы можете объединить их в одну функцию с помощью небольшой утилиты. Вот один из способов сделать это:

function combine(...functions) {
  return (...args) =>
    functions
      .filter(func => typeof func === 'function')
      .forEach(func => func(...args));
}

Тут мы создаем функцию, которая принимает список функций для их объединения. Он возвращает новый колбек, который вызывает их всех по очереди с одинаковыми аргументами.

Эту функцию можно использовать таким образом:

function ToolTip(props) {
  const [isVisible, setVisible] = React.useState(false);
  return (
     setVisible(true), props.onMouseIn)}
      onMouseOut={combine(() => setVisible(false), props.onMouseOut)}
    />
  );
}

7. Используйте значения по умолчанию

Убедитесь что вы дали достаточное количество значений по умолчанию (defaults — дефолтных значений) вашим пропсам. Таким образом вы снизите количество обязательных для передачи пропсов. Это очень упростит ваш API.

Возьмите, к примеру, обработчик onClick. Если в вашем коде нет необходимости в этом обработчике, используйте пустую функцию (noop-function) в качестве пропа по умолчанию. Таким образом вы сможете вызывать его в своем коде, как если бы он всегда передавался.

Другой пример может быть для пользовательского ввода. Предположим, что входная строка является пустой строкой, если обратное явно не указано. Это позволит вам убедиться, что вы всегда имеете дело со строковым объектом, а не с чем-то неопределенным или нулевым.

8. Не надо переименовывать атрибуты HTML

HTML как язык имеет свои пропсы — или атрибуты, и он сам по себе является API интерфейсом элементов HTML. Так почему бы не продолжать использовать этот API?

Как мы упоминали ранее, сведение к минимуму поверхности API (API surface) и его интуитивность — это полезные методы для улучшения API ваших компонентов. Так что вместо того чтобы создавать свой screenReaderLabel проп, почему бы просто не использовать уже существующий aria-label?

Держитесь подальше от переименования любых существующих атрибутов HTML для вашей собственной «простоты использования». Вы ведь даже не заменяете существующий API — вы просто добавляете свой собственный поверх него. Люди по-прежнему могут передавать aria-label вместе с вашим пропом screenReaderLabel — и какое тогда должно быть окончательное значение?

Кроме того, убедитесь что вы никогда не переопределяете HTML атрибуты в ваших компонентах. Отличным примером является атрибут type элемента