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

Пишем 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>

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

<Button>Click me</Button>
<Button primary>Click me</Button>

Теперь, как это обычно и бывает с кнопками, вам понадобятся еще несколько вариантов. Вот как выглядит таблица нескольких пропсов для кнопок:

Есть несколько пропсов, которые можно использовать для изменения внешнего вида кнопки. Что будет если кто-то использует их вместе?

<Button primary destructive>
  Click me
</Button>

Победит ли кто-нибудь из них? От чего это зависит? От порядка?

Зачем вообще кому-то это писать? Существует ли реальный случай когда вам нужно сказать "Дайте мне primary destructive кнопку"?

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

Для того кто решает каким будет API, важно:

1. минимизировать ошибки
2. минимизировать путаницу вокруг API

Итак, вот совет № 1: не создавайте конфликтующие пропсы.

Мы можем довольно легко исправить приведенный выше код, используя проп который позволит получить список вариантов. Назовем его appearance (внешний вид)

<Button appearance="default">Click me</Button>
<Button appearance="primary">Click me</Button>
<Button appearance="destructive">Click me</Button>

Мы можем добавить список поддерживаемых вариантов для appearance используя prop-types (типы пропсов).

Button.PropTypes = {
  appearance: PropTypes.oneOf(['default', 'primary', 'secondary', 'link', 'destructive'])
}

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

<Button appearance="danger">Click me</Button>

Внимание: неправильный тип пропа:
Недействительный `prop` `appearance` в значении `danger` присвоен в `Button`,
возможно только одно из этих значений: `["default", "primary", "secondary", "link", "destructive"]`

Этот совет довольно прост в реализации, но он сделает ваш API намного проще в использовании (и поддержке).

От переводчика — я будут обновлять список статей этой серии (в начале) по мере перевода и выхода новых статей.