Иван Ганев IvanGanev

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

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

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

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

Пишем API для React компонентов, часть 1: не создавайте конфликтующие пропсы

Пишем API для React компонентов, часть 2: давайте названия поведению, а не способам взаимодействия

Пишем API для React компонентов, часть 3: порядок пропсов важен

Пишем API для React компонентов, часть 4: опасайтесь Апропакалипсиса!

Пишем API для React компонентов, часть 5: просто используйте композицию

Пишем API для React компонентов, часть 6: создаем связь между компонентами

Поговорим о формах.

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

Здесь много чего происходит, взглянем на API

Пишем API для React компонентов, часть 1: не создавайте конфликтующие пропсы

Пишем API для React компонентов, часть 2: давайте названия поведению, а не способам взаимодействия

Пишем API для React компонентов, часть 3: порядок пропсов важен

Пишем API для React компонентов, часть 4: опасайтесь Апропакалипсиса!

Пишем API для React компонентов, часть 5: просто используйте композицию

Пишем API для React компонентов, часть 6: создаем связь между компонентами

У нас есть компонент значка:

<Badge count={12} />

Вы видели их в различных приложениях, они показывают количество объектов в виде числа.

В cosmos Badge (значок) имеет несколько цветов для каждого конкретного контекста (информация, опасность и т.д.)

Пишем API для React компонентов, часть 1: не создавайте конфликтующие пропсы

Пишем API для React компонентов, часть 2: давайте названия поведению, а не способам взаимодействия

Пишем API для React компонентов, часть 3: порядок пропсов важен

Пишем API для React компонентов, часть 4: опасайтесь Апропакалипсиса!

Пишем API для React компонентов, часть 5: просто используйте композицию

Пишем API для React компонентов, часть 6: создаем связь между компонентами

Поговорим о компоненте Avatar.

<Avatar image="simons-cat.png" />

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

Пишем API для React компонентов, часть 1: не создавайте конфликтующие пропсы

Пишем API для React компонентов, часть 2: давайте названия поведению, а не способам взаимодействия

Пишем API для React компонентов, часть 3: порядок пропсов важен

Пишем API для React компонентов, часть 4: опасайтесь Апропакалипсиса!

Пишем API для React компонентов, часть 5: просто используйте композицию

Пишем API для React компонентов, часть 6: создаем связь между компонентами

Давайте начнем с простого компонента React, который отображает тег якоря (anchor tag):

<Link href="sid.studio">Click me</Link>

// будет отрендерено в:

<a href="sid.studio" class="link">Click me</a>

Вот как выглядит код компонента:

const Link = props => {
  return (
    <a href={props.href} className="link">
      {props.children}
    </a>
  )
}

Мы также хотим чтобы можно было добавлять к элементу такие html-атрибуты, как id, target, title, data-attr и т.д.

Пишем API для React компонентов, часть 1: не создавайте конфликтующие пропсы

Пишем API для React компонентов, часть 2: давайте названия поведению, а не способам взаимодействия

Пишем API для React компонентов, часть 3: порядок пропсов важен

Пишем API для React компонентов, часть 4: опасайтесь Апропакалипсиса!

Пишем API для React компонентов, часть 5: просто используйте композицию

Пишем API для React компонентов, часть 6: создаем связь между компонентами

У нас есть компонент переключатель — Switch, который принимает проп, давайте пока назовем его something (что-то).

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

<Switch something={fn} />

React дает нам возможность называть проп как нам угодно: handler / clickHandler / onClick / onToggle и т.д

Популярным стало соглашение о том, что название обработчика событий должно начинаться с on, например, onClick. Это связано с тем, что в спецификации HTML есть множество обработчиков, которые уже следуют этому соглашению: onkeydown, onchange, onclick и т.д.

Повторное использование уже существующего соглашения — отличная идея, разработчикам не придется запоминать что-то новое.

Окей, как насчет onClick?

Пишем API для React компонентов, часть 1: не создавайте конфликтующие пропсы

Пишем API для React компонентов, часть 2: давайте названия поведению, а не способам взаимодействия

Пишем API для React компонентов, часть 3: порядок пропсов важен

Пишем API для React компонентов, часть 4: опасайтесь Апропакалипсиса!

Пишем API для React компонентов, часть 5: просто используйте композицию

Пишем API для React компонентов, часть 6: создаем связь между компонентами

Этот пост — перевод первой статьи из серии статей Writing good component API, за авторством @Sid. При переводе, в любой непонятной ситуации, я буду руководствоваться официальным переводом документации React JS на русский язык

Когда речь идет о React компонентах, ваши пропсы — это ваш API.

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

Эта серия статей вдохновлена статьями и лекциями от Sebastian Markbåge, Brent Jackson, Jenn Creighton и A. Jesse Jiryu Davis.

После прочтения множества статей + лекций, и после более года проектирования дизайн системы cosmos, я пришел к этим принципам разработки.

Начнем с простого.

У нас есть кнопка:

<Button>Click me</Button>