Spaghettify превращает любой статический HTML-сайт в одностраничное приложение с навигацией на основе AJAX и функциями сохранения элементов DOM. Для этого он реализует перехватчик DOM и процессор промежуточного программного обеспечения , который фиксирует события щелчка по ссылке, извлекает каждый запрошенный документ через XHR и обрабатывает ответ, передавая его через ряд функций промежуточного программного обеспечения перед обновлением документа браузера.
Эти функции промежуточного программного обеспечения представляют собой подключаемые обработчики ввода-вывода, которые соблюдают принцип единой ответственности и соответствуют полному конвейеру шагов, которые можно разделить на перехваты промежуточного программного обеспечения onBeforeComplete
, которые НЕ изменяют DOM текущей страницы, и перехватчики промежуточного программного обеспечения onAfterComplete
, которые действительно применяют свои изменения. (следовательно, мутировать) непосредственно в DOM текущей страницы после его внедрения.
Весь проект построен на основе TypeScript и реализует несколько полифилов и стратегий кодирования для расширения поддержки старых устаревших браузеров, таких как MSIE11.
Минимальные требования для запуска этого проекта в режиме разработки или в рабочем режиме, а также его сценариев разработки — node v12.16.0
и npm v.6.14.15
или более поздние версии. Вероятно, этот проект будет работать без проблем на более старых версиях node
и npm
, но мы рекомендуем использовать последние версии LTS.
Этот проект использует BabelJS и Webpack для компиляции кода в режиме разработки, запуска сборок, обслуживания файлов демонстрационного сайта и оптимизации кода.
Для вашего удобства все взаимодействие с BabelJS
и Webpack
вынесено в специальные скрипты npm.
В качестве первого шага к созданию среды разработки или производственной сборки запустите npm install
yarn
или npm, чтобы получить все необходимые зависимости для этого проекта.
Пожалуйста, запустите yarn build
или npm run build
из окна терминала.
Сборщик проекта пройдёт по всему дереву приложения и построит артефакт JavaScript в папку /dist
в виде spaghettify.js
. Для вашего удобства там же будут сохранены и другие полезные пакеты.
Могу ли я получить Spaghettify из реестра npm? На момент написания этой статьи приоритетами проекта являются дальнейшее увеличение охвата тестами и расширение возможностей API за счет расширенной поддержки пользовательских перехватчиков промежуточного программного обеспечения. На данный момент Spaghettify предназначен для использования в качестве зависимости от браузера, но его распространение в виде пакета NPM находится в планах. Пожалуйста, зайдите в ближайшее время для получения обновлений.
Вы можете создавать экземпляры Spaghettify и взаимодействовать с ними через удобный API-интерфейс с глобальными переключателями, перехватчиками маршрутов, исключениями и флагами атрибутов сохранения состояния и, что не менее важно, индикаторами прогресса загрузки и обработчиками.
После успешной компиляции Spaghettify вы можете импортировать и создать его экземпляр в своем приложении следующим образом:
< script type =" text/javascript " src =" /dist/spaghettify.js " > </ script >
< script type =" text/javascript " >
new Spaghettify ( {
enabled : true ,
routes : [ '*.html' , 'content/*' ] ,
excludeByAttr : 'no-spa' ,
loadProgress : true ,
persistAttr : 'data-persist' ,
} ) ;
</ script >
Как видите, Spaghettify может принимать объект конфигурации при создании экземпляра. Обратите внимание, что все поля являются необязательными и даже сам объект конфигурации также не является обязательным. Если не указано иное, Spaghettify будет создан с параметрами по умолчанию, как описано в таблице ниже.
Объект настроек конфигурации Spaghettify можно резюмировать следующим образом:
Поле | Тип | По умолчанию | Описание |
---|---|---|---|
enabled | Boolean | true | Включает или отключает Spaghettify при создании экземпляра. |
routes | String[] | ['*'] | Определяет шаблоны маршрутов, которые будут перехватываться и обслуживаться через Spaghettify. Поддерживает глобальные токены. |
excludeByAttr | String | undefined | Определяет токен атрибута данных исключения (с префиксом data- или без него). Ссылки, украшенные этим атрибутом, будут пропущены Spaghettify. |
loadProgress | Boolean Function | false | Включает или нет встроенный индикатор выполнения. Он также может принимать обработчик функции, который будет получать целое число процентного прогресса при загрузке. |
persistAttr | String | undefined | Определяет атрибут данных флага сохранения состояния пользовательского интерфейса (с префиксом data- или без него). Элементы, украшенные этим атрибутом, сохранят свое состояние при навигации по странице. |
Обратите внимание, что все параметры конфигурации (и сама полезная нагрузка параметров) являются необязательными и принимают значение по умолчанию, если они не объявлены явно.
Spaghettify взаимодействует с вашим текущим документом, внутренне привязывая обработчики событий к подходящим ссылкам. Чтобы предотвратить утечки памяти или если вы хотите остановить Spaghettify до тех пор, пока он не будет снова восстановлен, вам нужно уничтожить его следующим образом:
< script type =" text/javascript " >
// First, we instantiate Spaghettify
const spa = new Spaghettify ( ) ;
// Then we dispose it after use
spa . destroy ( ) ;
</ script >
Все ссылки настроены Spaghettify как подлежащие перехвату. Механизм внутреннего менеджера событий оценит, может ли ссылка рассматриваться как запрос AJAX, путем проверки значения href ссылки на токены routes
glob.
Однако мы можем обойти этот шаг заранее, настроив параметр excludeByAttr
со значением атрибута с префиксом data-
или без него.
Тем не менее, ради семантики, Spaghettify будет рассматривать только элементы ссылок, настроенные с полноценным атрибутом.
< script type =" text/javascript " >
new Spaghettify ( {
excludeByAttr : 'skip-me' ,
} ) ;
</ script >
<!-- Spaghettify will disregard the following link -->
< a href =" foo.html " data-skip-me > Skip this link </ a >
Настроенный атрибут может быть заполнен любым значением или вообще отсутствовать. Spaghettify в любом случае проигнорирует это значение.
Как мы уже видели, опция конфигурации loadProgress
может принимать Boolean
примитивное значение или обработчик функции .
< script type =" text/javascript " >
new Spaghettify ( {
loadProgress : true ,
} ) ;
</ script >
Если это не настроено явно или не установлено значение false
, индикатор выполнения не будет отображаться. Если указано значение true
, Spaghettify отобразит анимированный красный индикатор выполнения в верхней части области просмотра. Индикатор выполнения показывает фактический ход загрузки.
Однако потребители могут захотеть реализовать свои собственные визуальные решения для отображения информации о ходе загрузки. Spaghettify решает эти проблемы, предоставляя обработчик прогресса загрузки, который ожидает в своей подписи параметр целочисленного значения, который будет принимать значения от 0
до 100
, когда страницы запрашиваются и загружаются через HXR.
< script type =" text/javascript " >
new Spaghettify ( {
loadProgress : function onLoad ( progress ) {
console . log ( progress ) ; // Will log values from 0 to 100
} ,
} ) ;
</ script >
Spaghettify реализует экспериментальный API для сохранения состояния в выбранных аннотированных узлах DOM при навигации по страницам. Для этого вам просто нужно настроить токен значения в опции persistAttr
, а затем аннотировать те элементы DOM, состояние которых вы хотите сохранить, с помощью эквивалентного атрибута data-
с уникальным значением каждый:
< script type =" text/javascript " >
new Spaghettify ( {
persistAttr : 'persist-id' ,
} ) ;
</ script >
< input type =" text " data-persist-id =" my-input " />
Вы можете явно добавлять к значению префикс data-
или нет, но Spaghettify потребует от вас аннотировать сохраняемые элементы DOM с помощью полного синтаксиса атрибутов данных.
Обратите внимание : значения атрибутов должны быть уникальными. Spaghettify выдаст исключение, если более одного элемента разного типа настроено с одинаковым значением атрибута.
Стоит подчеркнуть, что постоянство будет применяться ко всему Node
DOM, поэтому оно будет охватывать не только внутренний HTML-код элемента, но и собственное состояние касания для элементов управления вводом. И все это независимо от изменений внешнего HTML.
Вы можете создать среду разработки, запустив в консоли yarn dev
или npm run dev
.
Система сгенерирует все артефакты и будет обслуживать сайт песочницы (подробнее ниже) с http://localhost:3000 (или любого другого порта по вашему выбору, если вы добавите параметр --port=PORT
к команде dev
, где PORT
— желаемый порт) в режиме просмотра , поэтому приложение будет перекомпилировано при изменении исходного кода.
Сайт-песочница — это небольшое, очень упрощенное веб-приложение, которое служит игровой площадкой и ареной тестирования для отладки Spaghettify в реальной среде. Он имеет довольно упрощенный стиль и состоит из набора различных иерархических страниц, на которых изображены следующие ключевые функции:
index.html
содержит встроенный экземпляр Spaghettify для демонстрационных целей. Все остальные документы реализуют такой экземпляр как импортированный скрипт. Вам не нужно импортировать Spaghettify в каждый документ, только в запись. Однако это позволяет запустить Spaghettify из любого документа после перезагрузки окна браузера в демонстрационных целях. В реальном производственном сценарии Spaghettify можно (и нужно) импортировать и создать экземпляр только один раз в месте входа./sandbox
и дочерней подпапкой /sandbox/content
, поэтому участники могут при необходимости поэкспериментировать с селекторами ссылок, указывающими на подпапки./sandbox/content
содержат либо встроенный, либо импортированный пользовательский JavaScript, который Spaghettify обработает, повторно внедрит и выполнит при необходимости. ESLint в настоящее время включен в кодовой базе Spaghettify, и проверка проверки будет запущена после сборки проекта. Вы можете настроить свою IDE для автоматического предоставления оценки проверки при внесении изменений. Более того, вы можете запустить анализ кода в любое время, запустив npm run lint
или yarn lint
в консоли терминала.
Вы можете добавить тесты в кодовую базу или выполнить существующие, запустив npm test
или yarn test
в консоли терминала. Данные о покрытии кода собираются и хранятся в удобно отформатированном документе по адресу /coverage/lcov-report
. Для отображения отчетов о покрытии на экране добавьте параметр --coverage
к команде test
.
Вы также можете проверить онлайн подробный отчет о тестировании на сайте Coveralls.
Copyright 2021 Пабло Дилман
Настоящим бесплатно любому лицу, получившему копию этого программного обеспечения и связанных с ним файлов документации («Программное обеспечение»), предоставляется разрешение на работу с Программным обеспечением без ограничений, включая, помимо прочего, права на использование, копирование, изменение, объединение. публиковать, распространять, сублицензировать и/или продавать копии Программного обеспечения, а также разрешать лицам, которым предоставлено Программное обеспечение, делать это при соблюдении следующих условий:
Вышеупомянутое уведомление об авторских правах и данное уведомление о разрешении должны быть включены во все копии или существенные части Программного обеспечения.
ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ГАРАНТИЯМИ ТОВАРНОЙ ЦЕННОСТИ, ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ. НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ АВТОРЫ ИЛИ ОБЛАДАТЕЛИ АВТОРСКИХ ПРАВ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ ПРЕТЕНЗИИ, УБЫТКИ ИЛИ ДРУГУЮ ОТВЕТСТВЕННОСТЬ, БУДЬ В ДЕЙСТВИЯХ ПО КОНТРАКТУ, ПРАВОНАРУШЕНИЮ ИЛИ ДРУГИМ ОБРАЗОМ, ВОЗНИКАЮЩИЕ ОТ, ИЗ ИЛИ В СВЯЗИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ ИЛИ ДРУГИМИ СДЕЛКАМИ, ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ.