Пишем 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>Теперь, как это обычно и бывает с кнопками, вам понадобятся еще несколько вариантов. Вот как выглядит таблица нескольких пропсов для кнопок:
| имя | описание | тип | значение по умолчанию |
|---|---|---|---|
primary |
нужно для обозначения основного действия | boolean |
false |
secondary |
для действий которые менее важны | boolean |
false |
destructive |
Опасная кнопка, для действий с которыми пользователь должен быть осторожен, пример: удаление | boolean |
false |
link |
нужно для отображения кнопки как ссылки | boolean |
false |
Есть несколько пропсов, которые можно использовать для изменения внешнего вида кнопки. Что будет если кто-то использует их вместе?
<Button primary destructive>
Click me
</Button>Победит ли кто-нибудь из них? От чего это зависит? От порядка?
Зачем вообще кому-то это писать? Существует ли реальный случай когда вам нужно сказать "Дайте мне primary destructive кнопку"?
В большинстве случаев это ошибка. Но если разработчикам вообще приходится задавать такие вопросы (как выше приведенные), это, вероятно, не очень хороший API.
Для того кто решает каким будет API, важно:
- минимизировать ошибки
- минимизировать путаницу вокруг 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 намного проще в использовании (и поддержке).
От переводчика — я будут обновлять список статей этой серии (в начале) по мере перевода и выхода новых статей.
