Как стать автором
Обновить

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

JavaScript *ReactJS *
Перевод
Tutorial
Автор оригинала: Sid
Пишем 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-1


<Button>Click me</Button>

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


button-2


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

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


имя описание тип значение по умолчанию
primary нужно для обозначения основного действия boolean false
secondary для действий которые менее важны boolean false
destructive Опасная кнопка, для действий с которыми пользователь должен быть осторожен, пример: удаление boolean false
link нужно для отображения кнопки как ссылки boolean false

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


button-3


<Button primary destructive>
  Click me
</Button>

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


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


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


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


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

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


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


button-4


<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-1


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

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

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


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

Теги:
Хабы:
Всего голосов 11: ↑10 и ↓1 +9
Просмотры 5.6K
Комментарии Комментарии 3