| <%= getTranslation('option') %> | 5 |<%= getTranslation('type') %> | 6 |<%= getTranslation('default') %> | 7 |<%= getTranslation('description') %> | 8 |
|---|---|---|---|
| solidClassnameArray | 13 |array | 14 |[] | 15 |<%= getTranslation('option-solidClassnameArray') %> | 16 |
| fromViewportWidth | 19 |number | 20 |0 | 21 |<%= getTranslation('option-fromViewportWidth') %> | 22 |
| pagerThreshold | 25 |number | 26 |0.5 | 27 |<%= getTranslation('option-pagerThreshold') %> | 28 |
| hasToUpdateHash | 31 |boolean | 32 |false | 33 |<%= getTranslation('option-hasToUpdateHash') %> | 34 |
| scrollAdjustThreshold | 37 |number | 38 |0 | 39 |<%= getTranslation('option-scrollAdjustThreshold') %> | 40 |
| scrollAdjustDelay | 43 |number | 44 |600 | 45 |<%= getTranslation('option-scrollAdjustDelay') %> | 46 |
| pagerLinkActiveClassname | 49 |string | 50 |pager-link-active | 51 |<%= getTranslation('option-pagerLinkActiveClassname') %> | 52 |
| isScrollHandled | 55 |boolean | 56 |true | 57 |<%= getTranslation('option-isScrollHandled') %> | 58 |
| onInit | 61 |function | 62 |null | 63 |<%= getTranslation('option-onInit') %> | 64 |
| onBind | 67 |function | 68 |null | 69 |<%= getTranslation('option-onBind') %> | 70 |
| onUnbind | 73 |function | 74 |null | 75 |<%= getTranslation('option-onUnbind') %> | 76 |
| onDestroy | 79 |function | 80 |null | 81 |<%= getTranslation('option-onDestroy') %> | 82 |
| onActiveLayerChange | 85 |function | 86 |null | 87 |<%= getTranslation('option-onActiveLayerChange') %> | 88 |
<div class="fixed" data-immerser>
2 | <div data-immerser-mask>
3 | <div data-immerser-mask-inner>
4 | <!-- <%= getTranslation('your-markup') %> -->
5 | </div>
6 | </div>
7 | <div data-immerser-mask>
8 | <div data-immerser-mask-inner>
9 | <!-- <%= getTranslation('your-markup') %> -->
10 | </div>
11 | </div>
12 | </div>a:hover,
2 | a._hover {
3 | color: magenta;
4 | }// adding or removing node, that changes DOM height
2 | document.appendChild(someNode);
3 | document.removeChild(anotherNode);
4 |
5 | // then explicitly redraw immerser
6 | immerserInstance.onDOMChange();// <%= getTranslation('dont-import-if-umd-line-1') %>
2 | // <%= getTranslation('dont-import-if-umd-line-2') %>
3 | import Immerser from 'immerser';
4 |
5 | const immerserInstance = new Immerser({
6 | // <%= getTranslation('data-attribute-will-override-this-option-line-1') %>
7 | // <%= getTranslation('data-attribute-will-override-this-option-line-2') %>
8 | solidClassnameArray: [
9 | {
10 | logo: 'logo--contrast-lg',
11 | pager: 'pager--contrast-lg',
12 | language: 'language--contrast-lg',
13 | },
14 | {
15 | pager: 'pager--contrast-only-md',
16 | menu: 'menu--contrast',
17 | about: 'about--contrast',
18 | },
19 | {
20 | logo: 'logo--contrast-lg',
21 | pager: 'pager--contrast-lg',
22 | language: 'language--contrast-lg',
23 | },
24 | {
25 | logo: 'logo--contrast-only-md',
26 | pager: 'pager--contrast-only-md',
27 | language: 'language--contrast-only-md',
28 | menu: 'menu--contrast',
29 | about: 'about--contrast',
30 | },
31 | {
32 | logo: 'logo--contrast-lg',
33 | pager: 'pager--contrast-lg',
34 | language: 'language--contrast-lg',
35 | },
36 | ],
37 | hasToUpdateHash: true,
38 | fromViewportWidth: 1024,
39 | pagerLinkActiveClassname: 'pager__link--active',
40 | scrollAdjustThreshold: 50,
41 | scrollAdjustDelay: 600,
42 | onInit(immerser) {
43 | // <%= getTranslation('callback-on-init') %>
44 | },
45 | onBind(immerser) {
46 | // <%= getTranslation('callback-on-bind') %>
47 | },
48 | onUnbind(immerser) {
49 | // <%= getTranslation('callback-on-unbind') %>
50 | },
51 | onDestroy(immerser) {
52 | // <%= getTranslation('callback-on-destroy') %>
53 | },
54 | onActiveLayerChange(activeIndex, immerser) {
55 | // <%= getTranslation('callback-on-active-layer-change') %>
56 | },
57 | });
58 | <div class="fixed" data-immerser>
2 | <div class="fixed__pager pager" data-immerser-pager data-immerser-solid="pager"></div>
3 | <a href="#reasoning" class="fixed__logo logo" data-immerser-solid="logo"><%= getTranslation('immerser') %></a>
4 | <div class="fixed__menu menu" data-immerser-solid="menu">
5 | <a href="#reasoning" class="menu__link"><%= getTranslation('menu-link-reasoning') %></a>
6 | <a href="#how-to-use" class="menu__link"><%= getTranslation('menu-link-how-to-use') %></a>
7 | <a href="#how-it-works" class="menu__link"><%= getTranslation('menu-link-how-it-works') %></a>
8 | <a href="#options" class="menu__link"><%= getTranslation('menu-link-options') %></a>
9 | <a href="#recipes" class="menu__link"><%= getTranslation('menu-link-recipes') %></a>
10 | </div>
11 | <div class="fixed__language language" data-immerser-solid="language">
12 | <a href="/" class="language__link">english</a>
13 | <a href="/ru.html" class="language__link">по-русски</a>
14 | </div>
15 | <div class="fixed__about about" data-immerser-solid="about">
16 | <%= getTranslation('copyright') %>
17 | <a href="https://github.com/dubaua/immerser"><%= getTranslation('github') %></a>
18 | <a href="mailto:dubaua@gmail.com">dubaua@gmail.com</a>
19 | </div>
20 | </div>
21 |
22 | <div data-immerser-layer data-immerser-layer-config='{"logo": "logo--contrast", "pager": "pager--contrast", "social": "social--contrast"}' id="reasoning"></div>
23 | <div data-immerser-layer data-immerser-layer-config='{"menu": "menu--contrast", "about": "about--contrast"}' id="how-to-use"></div>
24 | <div data-immerser-layer data-immerser-layer-config='{"logo": "logo--contrast", "pager": "pager--contrast", "social": "social--contrast"}' id="how-it-works"></div>
25 | <div data-immerser-layer data-immerser-layer-config='{"menu": "menu--contrast", "about": "about--contrast"}' id="options"></div>
26 | <div data-immerser-layer data-immerser-layer-config='{"logo": "logo--contrast", "pager": "pager--contrast", "social": "social--contrast"}' id="recipes"></div>
27 | .fixed {
2 | position: fixed;
3 | top: 2em;
4 | bottom: 3em;
5 | left: 3em;
6 | right: 3em;
7 | z-index: 1;
8 | }
9 | .fixed__pager {
10 | position: absolute;
11 | top: 50%;
12 | left: 0;
13 | transform: translate(0, -50%);
14 | }
15 | .fixed__logo {
16 | position: absolute;
17 | top: 0;
18 | left: 0;
19 | }
20 | .fixed__menu {
21 | position: absolute;
22 | top: 0;
23 | right: 0;
24 | }
25 | .fixed__language {
26 | position: absolute;
27 | bottom: 0;
28 | left: 0;
29 | }
30 | .fixed__about {
31 | position: absolute;
32 | bottom: 0;
33 | right: 0;
34 | }
35 | .pager,
36 | .logo,
37 | .menu,
38 | .language,
39 | .about {
40 | color: black;
41 | }
42 | .pager--contrast,
43 | .logo--contrast,
44 | .menu--contrast,
45 | .language--contrast,
46 | .about--contrast {
47 | color: white;
48 | }
49 | | <%= getTranslation('option') %> | 56 |<%= getTranslation('type') %> | 57 |<%= getTranslation('default') %> | 58 |<%= getTranslation('description') %> | 59 |
|---|
19 | Sometimes designers create complex logic and fix parts of the interface. 20 | Also they colour page sections contrasted. How to deal with this mess? 21 |
22 |23 | Immerser comes to help you. It’s a javascript library to change fixed elements on scroll. 24 |
25 |26 | Immerser fast, because it calculates states once on init. 27 | Then it watches the scroll position and schedules redraw document in the next event loop tick with requestAnimationFrame. 28 | Script changes transform property, so it uses graphic hardware acceleration. 29 |
30 |31 | Immerser is written on vanilla js. Only %%BUNDLESIZE%%Kb gzipped. 32 |
33 | `, 34 | 35 | 'terms-title': 'Terms', 36 | 'terms-content': ` 37 |
38 | Immerser root — is the parent
39 | container for your fixed parts solids.
40 | Actually, solids are positioned absolutely to fixed immerser root. The
41 | layers are sections of your page.
42 | Also you may want to add
43 | pager to navigate through layers
44 | and indicate active state.
45 |
Using npm:
', 50 | 'install-yarn-label': 'Using yarn:
', 51 | 'install-browser-label': 'Or if you want to use immerser in browser as global variable:
', 52 | 53 | 'prepare-your-markup-title': 'Prepare Your Markup', 54 | 'prepare-your-markup-content': ` 55 |First, setup fixed container as the immerser root container, and add the data-immerser attribute.
Next place absolutely positioned children into the immerser parent and add data-immerser-solid="solid-id" to each.
Then add data-immerser-layer attribute to each section and pass configuration in
58 | data-immerser-layer-config='{"solid-id": "classname-modifier"}'. Otherwise, you can pass configuration as
59 | solidClassnameArray option to immerser. Config should contain JSON describing what class should be
60 | applied on each solid element, when it's over a section.
Also feel free to add data-immerser-pager to create a pager for your layers.
67 | Apply colour and background styles to your layers and solids according to your classname configuration passed in data attribute or options. 68 | I’m using BEM methodology in this example. 69 |
70 | `, 71 | 72 | 'dont-import-if-umd-line-1': `You don't have to import immerser`, 73 | 'dont-import-if-umd-line-2': `if you're using it in browser as global variable`, 74 | 'data-attribute-will-override-this-option-line-1': 'this option will be overridden by options', 75 | 'data-attribute-will-override-this-option-line-2': 'passed in data-immerser-layer-config attribute in each layer', 76 | 77 | 'initialize-immerser-title': 'Initialize Immerser', 78 | 'initialize-immerser-content': `Include immerser in your code and create immerser instance with options.
`, 79 | 80 | 'callback-on-init': 'callback on init', 81 | 'callback-on-bind': 'callback on bind', 82 | 'callback-on-unbind': 'callback on unbind', 83 | 'callback-on-destroy': 'callback on destroy', 84 | 'callback-on-active-layer-change': 'callback on active layer change', 85 | 86 | 'how-it-works-title': 'How it Works', 87 | 'how-it-works-content': ` 88 |First, immerser gathers information about the layers, solids, window and document. Then it creates a statemap for each layer, containing all necessary information, when the layer is partially and fully in viewport.
89 |After that immerser modifies DOM, cloning all solids into mask containers for each layer and applying the classnames given in configuration. If you have added a pager, immerser also creates links for layers.
90 |Finally, immerser binds listeners to scroll and resize events. On resize, it will meter layers, the window and document heights again and recalculate the statemap.
91 |On scroll, immerser moves a mask of solids to show part of each solid group according to the layer below.
92 | `, 93 | 94 | 'options-title': 'Options', 95 | 'options-content': ` 96 |97 | You can pass options to immerser as data-attributes on layers or as object as function parameter. Data-attributes are 98 | processed last, so they override the options passed to the function. 99 |
100 | `, 101 | 102 | option: 'option', 103 | type: 'type', 104 | default: 'default', 105 | description: 'description', 106 | 107 | 'option-solidClassnameArray': 108 | 'Array of layer class configurations. Overriding by config passed in data-immerser-layer-config for corresponding layer. Configuration example is shown above', 109 | 'option-fromViewportWidth': 'A viewport width, from which immerser will init', 110 | 'option-pagerThreshold': 'How much next layer should be in viewport to trigger pager', 111 | 'option-hasToUpdateHash': 'Flag to control changing hash on pager active state change', 112 | 'option-scrollAdjustThreshold': 113 | 'A distance from the viewport top or bottom to the section top or bottom edge in pixels. If the current distance is below the threshold, the scroll adjustment will be applied. Will not adjust, if zero passed', 114 | 'option-scrollAdjustDelay': 'Delay after user interaction and before scroll adjust', 115 | 'option-pagerLinkActiveClassname': 'Added to each pager link pointing to active', 116 | 'option-isScrollHandled': 'Binds scroll listener if true. Set to false if you\'re using remote scroll controller', 117 | 'option-onInit': 'Fired after initialization. Accept an immerser instance as the only parameter', 118 | 'option-onBind': 'Fired after binding DOM. Accept an immerser instance as the only parameter', 119 | 'option-onUnbind': 'Fired after unbinding DOM. Accept an immerser instance as the only parameter', 120 | 'option-onDestroy': 'Fired after destroy. Accept an immerser instance as the only parameter', 121 | 'option-onActiveLayerChange': 122 | 'Fired after active layer change. Accept active layer index as first parameter and an immerser instance as second', 123 | 124 | 'cloning-event-listeners-title': 'Cloning Event Listeners', 125 | 'cloning-event-listeners-content': ` 126 |127 | Since immerser cloning nested nodes by default, all event listeners and data bound on nodes will be lost after 128 | init. Fortunately, you can markup the immerser yourself. It can be useful when you have event listeners 129 | on solids, reactive logic or more than classname switching. All you need is to place the number 130 | of nested immerser masks equal to the number of the layers. Look how I change the smiley emoji 131 | on the right in this page source. 132 |
133 | `, 134 | 135 | 'your-markup': 'your markup', 136 | 137 | 'handle-clone-hover-title': 'Handle Clone Hover', 138 | 'handle-clone-hover-content': ` 139 |
140 | As mentioned above, immerser cloning nested nodes to achieve changing on scroll. Therefore if you
141 | hover a partially visible element, only the visible part will change. If you want to synchronize all cloned links, just
142 | pass
143 | data-immerser-synchro-hover="hoverId" attribute. It will share _hover class between all
144 | nodes with this hoverId when the mouse is over one of them. Add _hover selector alongside your
145 | :hover pseudoselector to style your interactive elements.
146 |
151 | Immerser is not aware of changes in DOM, if you dynamically add or remove nodes. If you change height of the document
152 | and want immerser to recalculate and redraw solids, call onDOMChange method on the immerser instance.
153 |
19 | Иногда дизайнеры создают сложную логику и фиксируют части интерфейса. 20 | А еще они красят разделы страницы в контрастные цвета. Как с этим справиться? 21 |
22 |23 | Вам поможет иммёрсер — джаваскрипт библиотека для замены фиксированных элементов при прокрутке страницы. 24 |
25 |26 | Иммёрсер вычисляет состояния один раз в момент инициализации. 27 | Затем он следит за позицией скролла и планирует перерисовку документа 28 | в следующем такте цикла событий через метод requestAnimationFrame. 29 | Скрипт изменяет свойство transform, это задействует графический ускоритель. 30 |
31 |32 | Иммёрсер написан на чистом джаваскрипте. Всего %%BUNDLESIZE%%Кб в сжатии gzip. 33 |
34 | `, 35 | 36 | 'terms-title': 'Термины', 37 | 'terms-content': ` 38 |
39 | Корневой элемент иммёрсера — это родительский контейнер для ваших фиксированных блоков.
40 | Фактически они позиционированы абсолютно внутри фиксированного корневого элемента.
41 | Слои — это разделы страницы, окрашенные в разные цвета.
42 | Еще вы наверняка захотите добавить навигацию по разделам, выделяющую активный раздел.
43 |
Через npm:
', 48 | 'install-yarn-label': 'Через yarn:
', 49 | 'install-browser-label': 'Или если вы хотите использовать иммёрсер в браузере как глобальную переменную:
', 50 | 51 | 'prepare-your-markup-title': 'Подготовьте разметку', 52 | 'prepare-your-markup-content': ` 53 |Сначала настройте свой фиксированный контейнер как корневой элемент иммёрсера, добавив атрибут data-immerser
Затем расположите в нем абсолютно позиционированные дочерние элементы и добавьте каждому атрибут data-immerser-solid="solid-id" с идентификатором блока.
Добавьте каждому слою атрибут data-immerser-layer. Передайте конфигурацию в виде JSON в каждый слой с помощью атрибута
56 | data-immerser-layer-config='{"solid-id": "classname-modifier"}'.
57 | Также вы можете передать конфигурацию всех слоев массивом в параметре solidClassnameArray настроек.
58 | Конфигурация должна содержать описание классов для блоков, когда они находятся поверх слоя.
Так же вы можете добавить элемент с атрибутом data-immerser-pager для создания навигации.
65 | Добавьте стили цвета текста и фона на ваши блоки и слои с помощью классов, переданных в дата-атрибут или настройки. 66 | В примере я использую методологию БЭМ. 67 |
68 | `, 69 | 'dont-import-if-umd-line-1': `Вам не нужно импортировать иммёрсер,`, 70 | 'dont-import-if-umd-line-2': `если вы используете его в браузере как глобальную переменную`, 71 | 'data-attribute-will-override-this-option-line-1': 'будет переопределена настройками,', 72 | 'data-attribute-will-override-this-option-line-2': 'переданными в атрибут data-immerser-layer-config каждого слоя', 73 | 74 | 'initialize-immerser-title': 'Инициализируйте иммёрсер', 75 | 'initialize-immerser-content': `Добавьте иммёрсер в код и создайте экземпляр с настройками.
`, 76 | 77 | 'callback-on-init': 'колбек после инициализации', 78 | 'callback-on-bind': 'колбек после привязки к документу', 79 | 'callback-on-unbind': 'колбек после отвязки от документа', 80 | 'callback-on-destroy': 'колбек после уничтожения', 81 | 'callback-on-active-layer-change': 'колбек после смены активного слоя', 82 | 83 | 'how-it-works-title': 'Принцип работы', 84 | 'how-it-works-content': ` 85 |Сначала иммёрсер собирает информацию о слоях, блоках, окне и документе. Затем скрипт создает карту состояний для каждого слоя. Карта содержит размеры слоя, блоков и позиции их пересечений при скролле.
86 |После сбора информации скрипт копирует все блоки в маскирующий контейнер и применяет к каждому классы, переданные в настройках. Если вы добавили навигацию, то иммёрсер создаст ссылки на каждый слой.
87 |Затем иммёрсер подписывается на события скролла документа и изменения размеров окна.
88 |При скролле иммёрсер двигает маскирующий контейнер так, чтобы показывать часть каждой группы блоков для каждого слоя под ними. При изменении размеров окна скрипт рассчитает карту состояний заново.
89 | `, 90 | 91 | 'options-title': 'Настройки', 92 | 'options-content': ` 93 |94 | Вы можете передать настройки параметром функции конструктора или дата-атрибутом в документе. 95 | Дата-аттрибут обрабатывается последним, поэтому он переопределит настройки, переданные в конструктор. 96 |
97 | `, 98 | 99 | option: 'параметр', 100 | type: 'тип', 101 | default: 'значение по умолчанию', 102 | description: 'описание', 103 | 104 | 'option-solidClassnameArray': 105 | 'Массив настроек слоев. Конфигурация, переданная в data-immerser-layer-config перезапишет эту настройку для соответствующего слоя. Пример конфигурации показан выше', 106 | 'option-fromViewportWidth': 'Минимальная ширина окна для инициализации иммёрсера', 107 | 'option-pagerThreshold': 'Насколько должен следующий слой быть видим в окне, чтобы он стал активен в навигации', 108 | 'option-hasToUpdateHash': 'Флаг, контролирующий обновление хеша страницы', 109 | 'option-scrollAdjustThreshold': 110 | 'Дистанция до верха или низа окна браузера в пикселях. Если текущая дистанция меньше переданного значения, то скрипт подстроит положение скролла', 111 | 'option-scrollAdjustDelay': 'Сколько ждать бездействия пользователя, чтобы начать подстройку скролла', 112 | 'option-pagerLinkActiveClassname': 'Применяется, к каждой ссылке пейджера, ссылающуюся на активный слой', 113 | 'option-isScrollHandled': 'Подписывается на событие прокрутки, если включено. Выключите в случае, когда скроллом управляет внешний контроллер', 114 | 'option-onInit': 'Колбек после инициализации. Принимает один параметр — экземпляр иммёрсера', 115 | 'option-onBind': 'Колбек после привязки к документу. Принимает один параметр — экземпляр иммёрсера', 116 | 'option-onUnbind': 'Колбек после отвязки от документа. Принимает один параметр — экземпляр иммёрсера', 117 | 'option-onDestroy': 'Колбек после уничтожения. Принимает один параметр — экземпляр иммёрсера', 118 | 'option-onActiveLayerChange': 119 | 'Колбек после смены активного слоя. Принимает два параметра: индекс следующего слоя и экземпляр иммёрсера', 120 | 121 | 'cloning-event-listeners-title': 'Клонирование подписчиков событий', 122 | 'cloning-event-listeners-content': ` 123 |124 | Вы уже знаете, что иммёрсер клонирует элементы. 125 | Подписчики событий и данные, привязанные к нодам, не клонируются вместе с элементом. 126 | К счастью, вы можете разметить иммёрсер самостоятельно. 127 | Для этого разместите внутри корневого элемента маскирующие контейнеры для блоков по числу слоев. 128 | В таком случае скрипт не будет клонировать элементы. Подписчики и реактивная логика останутся нетронутыми. 129 | В примере на этой странице я создаю подписчик на клик по смайлу справа до инициализации. 130 |
131 | `, 132 | 133 | 'your-markup': 'ваша разметка', 134 | 135 | 'handle-clone-hover-title': 'Обработка наведения на границах слоев', 136 | 'handle-clone-hover-content': ` 137 |
138 | Если вы наведете мышь на элемент, находящийся на границе слоев,
139 | то псевдоселектор :hover сработает только на одну часть.
140 | Чтобы наведение сработало на все клоны элемента, задайте идентификатор наведения в атрибуте data-immerser-synchro-hover="hoverId".
141 | При наведении мыши на такой элемент, ко всем его клонам добавится класс _hover.
142 | Стилизуйте по этому селектору вместе с псевдоселектором :hover, чтобы добиться нужного эффекта.
143 |
148 | Иммёрсер не отслеживает изменения документа, если вы динамически добавляете или удаляете ноды. Если вы меняете высоту документа,
149 | и хотите, чтобы иммёрсер пересчитал и перерисовал блоки, вызовите метод onDOMChange у экземпляра иммёрсера.
150 |