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

Автор оригинала: Sid
  • Перевод
  • Tutorial
Пишем 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 намного проще в использовании (и поддержке).


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

Поделиться публикацией
AdBlock похитил этот баннер, но баннеры не зубы — отрастут

Подробнее
Реклама

Комментарии 3

    +1
    Я бы обобщил: подобные пропы не то, чтобы конфликтуют, они являются значениями одного и того же свойства объекта (как то размер, форма, цветовая гамма). Данный совет, кстати говоря, вполне справедлив не только для реакта )
      0

      Удобнее было бы не контролировать с помощью PropTypes постфактум, а дать сразу набор возможных значений


      Button.appearance = {
        default: 'default',
        primary: 'primary',
        secondary: 'secondary',
      }
      

      <Button appearance={Button.appearance.primary}>Click me</Button>
      
        0
        Типы пропсов реакта это стандартный и рекомендуемый способ управлять, ну, типами пропсов реакта — его понимают и разработчики, и инструменты разработки.

      Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

      Самое читаемое