Введение в Stimulus.js

Сеть движется довольно быстро, и выбрать подход для вашего внешнего интерфейса, который будет казаться разумным через год, сложно. Мой самый большой страх как разработчика — взять проект, к которому какое-то время не прикасались, и обнаружить, что документация по тому подходу, который они использовали, либо не существует, либо ее нелегко найти в Интернете.

Около года назад я начал использовать Stimulus и был очень доволен кодом, который выпускал. Это библиотека размером около 30 КБ, которая поощряет использование небольших повторно используемых фрагментов JavaScript в вашем приложении, организованных таким образом, что оставляет небольшие подсказки в вашем доступном HTML о том, где найти JavaScript, к которому он подключен. Это делает понимание того, как фрагмент JavaScript будет взаимодействовать с вашей страницей, почти таким же, как чтение псевдокода.

Stimulus был создан командой Basecamp — они недавно выпустили почтовый сервис HEY — чтобы помочь поддерживать JavaScript, который они пишут для своих веб-приложений. Исторически сложилось так, что Basecamp довольно хорошо поддерживает свои проекты с открытым исходным кодом, поэтому я совершенно уверен, что Stimulus был тщательно протестирован и будет поддерживаться в течение следующих нескольких лет.

Stimulus позволил мне создавать приложения таким образом, чтобы их можно было использовать повторно и они были доступны. Хотя я не думаю, что Stimulus захватит Интернет, как React и Vue, я думаю, что это полезный инструмент для изучения.

Терминология

Как и во всех фреймворках, в Stimulus есть предпочтительные термины для описания определенных вещей. К счастью (и это одна из основных причин, почему мне понравился Stimulus), есть только две вещи, о которых вам нужно знать:

• Контроллер
  Это относится к экземплярам классов JavaScript, которые являются строительными блоками вашего приложения. Можно с уверенностью сказать, что когда мы говорим о контроллерах Stimulus, мы говорим о классах JavaScript.
• Идентификатор
  Это имя мы будем использовать для ссылки на наш контроллер в нашем HTML, используя атрибут данных, общий для кодовых баз Stimulus.
  

Давайте прыгнем в стимул!

В следующих нескольких примерах я буду использовать код, который вы можете добавить в браузер, чтобы сразу приступить к работе через библиотеку, распространяемую через unpkg.com. Позже я расскажу о подходе webpack, который настоятельно рекомендуется, поскольку он позволяет улучшить организацию вашего кода и является подходом, используемым в Руководстве по Stimulus.

Шаблон

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

Довольно круто, правда? Давайте перейдем к тому, что все делает!

application.start

Эта строка указывает Stimulus добавить слушателей на страницу. Если вы вызовете его только один раз в верхней части страницы, прежде чем добавлять какой-либо код Stimulus, он вернет экземпляр основного контроллера Stimulus, который включает в себя register метода, который используется для сообщения Stimulus о классах, которые вы хотите подключить. к этому.

Контроллеры

Атрибут data-controller соединяет наш элемент HTML с экземпляром нашего класса JavaScript. В этом случае мы использовали идентификатор counter для подключения экземпляра JavaScript-класса CounterController к нашему элементу div . О связи этого идентификатора с контроллером мы сообщили Stimulus через метод application.register .

Stimulus будет постоянно отслеживать вашу страницу, когда элементы с этим атрибутом добавляются и удаляются. Когда на страницу добавляется новый фрагмент HTML с атрибутом data-controller , он инициализирует новый экземпляр соответствующего класса контроллера, а затем подключает элемент HTML. Если вы удалите этот элемент со страницы, он вызовет метод disconnect в классе контроллера.

Действия

Stimulus использует data data-action атрибута данных, чтобы четко определить, какая функция контроллера будет выполняться. Используя синтаксис event->controller#function , любой, кто читает HTML, сможет увидеть, что он делает. Это особенно полезно, поскольку снижает риск появления неожиданного кода из других файлов, упрощая навигацию по кодовой базе. Когда я впервые увидел подход, который поощряет Stimulus, это было похоже на чтение псевдокода.

В приведенном выше примере, когда кнопка запускает событие «щелчок», оно будет передано в функцию addOne в нашем контроллере «счетчик».

Цели

Цели — это способ явно определить, какие элементы будут доступны для вашего контроллера. Исторически я использовал сочетание ID, имен классов CSS и атрибутов данных, чтобы добиться этого, поэтому наличие единственного «Это способ сделать это», который настолько явный, делает код намного более последовательным.

Для этого необходимо определить ваши targets имена в вашем классе контроллера с помощью функции target и добавить имя к элементу с помощью data-target .

Как только вы настроите эти две части, ваш элемент будет доступен в вашем контроллере. В этом случае я настроил цель с именем «output», и к ней можно получить доступ с помощью this.outputTarget в функциях нашего контроллера.

Дублирующие цели

Если у вас есть несколько целей с одним и тем же именем, вы можете получить к ним доступ, используя версию целевого метода во множественном числе, в этом случае, когда я вызываю this.outputTargets , он возвращает массив, содержащий оба моих элемента div с атрибутом data-target="hello.output" . data-target="hello.output" .

Типы событий

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

Чтобы прослушивать события window или document (такие как изменение размера или переход пользователя в автономный режим), вам необходимо добавить «@window» или «@document» к типу event (например resize@window->console#logEvent вызовет функция logEvent ) на контроллере console при изменении размера окна.

Существует сокращенный способ присоединения общих событий, когда вы можете опустить тип события, и у него есть действие по умолчанию для типа элемента. Тем не менее, я настоятельно не рекомендую использовать сокращенную запись события, так как это увеличивает количество предположений, которые кто-то, менее знакомый со Stimulus, должен сделать о вашем коде.

Использует несколько контроллеров в одном элементе

Довольно часто вы можете захотеть разбить две части логики на отдельные классы, но сделать так, чтобы они отображались близко друг к другу в HTML. Stimulus позволяет вам соединять элементы с несколькими классами, размещая ссылки на оба в вашем HTML.

В приведенном выше примере я настроил объект basket , который занимается только подсчетом общего количества предметов в корзине, но также добавил child объект, который показывает количество сумок на предмет.

Передача данных вашему объекту

Stimulus предоставляет методы this.data.get и this.data.set внутри класса контроллера, это позволит вам изменять атрибуты данных, которые находятся в том же пространстве имен, что и идентификатор. Под этим я подразумеваю, что если вы хотите передать данные в свой контроллер стимулов из своего HTML, просто добавьте атрибут, такой как data-[identifier]-a-variable , к вашему HTML-элементу.

При вызове this.data.set он обновит значение в вашем HTML, чтобы вы могли видеть изменение значения при проверке элемента с помощью инструментов разработки вашего браузера.

Использование атрибутов данных в пространстве имен — действительно хороший способ сделать действительно ясным, какой атрибут данных для какой части кода.

Инициализировать, Подключено, Отключено

По мере роста вашего приложения вам, вероятно, потребуется подключаться к «событиям жизненного цикла», чтобы устанавливать значения по умолчанию, извлекать данные или обрабатывать связь в реальном времени. Stimulus имеет три встроенных метода, которые вызываются на протяжении всего жизненного цикла класса Stimulus.

Когда Stimulus увидит элемент с соответствующим атрибутом data-controller , он создаст новую версию вашего контроллера и вызовет функцию initialize . Это часто запускается при первой загрузке страницы, но также запускается, если вы добавляете новый HTML на свою страницу (например, через AJAX), содержащий ссылку на ваш контроллер. Он не будет запускаться, когда вы перемещаете элемент в новую позицию в вашем DOM.

После инициализации класса Stimulus подключит его к элементу HTML и вызовет функцию connect . Он также вызовет connect , если вы переместите элемент в DOM. Итак, если бы вы взяли элемент, удалили его из одного элемента, а затем добавили его куда-то еще, вы бы заметили, что будет вызываться только connect .

Функция disconnect будет запущена, когда вы удалите элемент со своей страницы, поэтому, например, если вы замените тело своего HTML, вы можете удалить любой код, который может потребоваться повторно запустить, если элемент не находится в такое же положение. Например, если у вас есть модный WYSIWYG-редактор, который добавляет к элементу много дополнительного HTML-кода, вы можете вернуть его в исходное состояние при вызове disconnect .

Наследование функциональности

Иногда вы можете захотеть использовать некоторые общие функции между вашими контроллерами Stimulus. Крутая вещь в Stimulus заключается в том, что (внутри) вы подключаете несколько ванильных классов JavaScript к элементам HTML, поэтому совместное использование функций должно показаться вам знакомым.

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

Использование в производстве

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

Вебпак

Если вы используете Webpack, вас ждет угощение! Stimulus был полностью создан для использования с Webpack. В их документации даже есть прекрасный стартовый набор для Webpack. Это позволит вам разбить ваши контроллеры на отдельные файлы, а Stimulus определит правильное имя для использования в качестве идентификатора.

Вам не нужно использовать веб-пакет, если вы хотите использовать Stimulus, но он значительно упрощает работу. Лично мне Stimulus была библиотекой, которая помогла мне познакомиться с Webpack и по-настоящему ощутить его ценность.

Соглашения об именах файлов

Во введении к этой статье я упомянул, что мне нравится использовать Stimulus, потому что он кажется организованным. Это действительно становится очевидным, когда вы комбинируете его с Webpack, который обеспечивает автоматическую загрузку и регистрацию контроллеров.

После того, как вы настроили Stimulus в Webpack, вам будет предложено назвать ваши файлы, например [identifier]_controller.js , где идентификатор — это то, что вы передадите в свой атрибут data-controller HTML.

По мере роста вашего проекта вы также можете перемещать контроллеры Stimulus в подпапки. Волшебным образом Stimulus преобразует символы подчеркивания в дефисы, а косые черты папки вперед — в два дефиса, которые затем станут вашим идентификатором. Так, например, имя файла chat/conversation_item_controller.js будет иметь идентификатор chat--conversation-item .

Поддержка меньшего количества JavaScript

Одна из моих любимых цитат — «Лучший код — это вообще отсутствие кода», я стараюсь применять этот подход ко всем своим проектам.

Веб-браузеры сильно развиваются, и я почти уверен, что большинство вещей, которые мне нужны для написания JavaScript сегодня, станут стандартизированными и встроены в браузер в течение следующих 5 лет. Хорошим примером этого является элемент details, когда я только начинал разработку, очень часто приходилось вручную кодировать эту функциональность вручную с помощью jQuery.

В результате, если я смогу написать доступный HTML с небольшим количеством JavaScript для удовлетворения своих потребностей, с мышлением «Сегодня это работает, но через 5 лет я хочу легко заменить это», я буду счастлив. разработчик. Это гораздо более достижимо, когда вы написали меньше кода для начала, что Stimulus поддается.

Сначала HTML, затем JavaScript

Один аспект, который мне очень нравится в подходе, который поощряет Stimulus, заключается в том, что я могу сосредоточиться на отправке HTML по сети своим пользователям, который затем немного оживляется с помощью JavaScript.

Я всегда был поклонником использования первых нескольких миллисекунд внимания пользователя, чтобы получить то, чем я должен поделиться с ним — прямо перед ним. Затем беспокоиться о настройке уровня взаимодействия, пока пользователь может начать обрабатывать то, что он видит.

Кроме того, если JavaScript по какой-либо причине выйдет из строя, пользователь все равно сможет видеть контент и взаимодействовать с ним без JavaScript. Например, вместо отправки формы через AJAX она будет отправлена ​​​​через традиционный запрос формы, который перезагружает страницу.

Заключение

Мне нравится создавать сайты, которые нуждаются в небольшом количестве поддерживаемого JavaScript для улучшения взаимодействия с пользователем, иногда приятно просто создать что-то, что кажется более простым. Иметь что-то легкое — это здорово, мне очень нравится, что без слишком большой когнитивной нагрузки довольно ясно, как организовать ваши файлы, и настроить небольшие хлебные крошки, которые намекают на то, как JavaScript будет работать с фрагментом HTML.

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

Слон в комнате — это то, как он выглядит по сравнению с такими, как React и Vue, но, на мой взгляд, это разные инструменты для разных требований. В моем случае я часто рендерю HTML со своего сервера и добавляю немного JavaScript, чтобы улучшить работу. Если бы я делал что-то более сложное, я бы рассмотрел другой подход (или отодвинул требования, чтобы мой код казался простым).

Дальнейшее чтение

• Домашняя страница стимула
  У них есть фантастическое руководство, в котором концепции, которые я изложил выше, рассматриваются гораздо глубже.
• Репозиторий Stimulus GitHub
  Я так много узнал о том, как работает Stimulus, изучая их код.
• Шпаргалка по стимулам
  Справочник уместился на одной странице.
• Стимул Форум
  Увидев, как другие люди работают со Stimulus, я действительно почувствовал, что его используют в дикой природе.