Documentation: <amp-sidebar>

Table of contents

amp-sidebar

Описание	Боковая панель предназначена для показа метаконтента, который не должен быть видимым постоянно (ссылок навигации, кнопок, меню и т. п.). Боковая панель может открываться нажатием кнопки, скрывая основной контент под собой.
Скрипт	`<script async custom-element="amp-sidebar" src="https://cdn.ampproject.org/v0/amp-sidebar-0.1.js"></script>`
Поддерживаемые макеты	nodisplay
Примеры	См. пример amp-sidebar на сайте AMP By Example.

Обзор

Компонент <amp-sidebar> нужен, чтобы скрывать метаконтент, не предназначенный для постоянного отображения (ссылки навигации, кнопки, меню и т. п.). Открывать и закрывать <amp-sidebar> можно нажатием кнопки, а также касанием за пределами боковой панели. Важно отметить, что дополнительные атрибуты с поддержкой запросов медиа в качестве значений позволяют показывать метаконтент в других частях сайта. При использовании дочерних элементов <nav toolbar="(media query)" toolbar-target="elementID"> содержание боковой панели может демонстрироваться поверх других частей основного контента.

Принципы работы

Компонент <amp-sidebar> должен быть включен как дочерний непосредственно в раздел <body>.
Боковая панель может появляться только с левой или с правой стороны страницы.
Компонент <amp-sidebar> может содержать любые допустимые элементы HTML (из числа поддерживаемых на AMP-страницах).
Компонент <amp-sidebar> может содержать следующие элементы AMP:
- <amp-accordion>
- <amp-img>
- <amp-fit-text>
- <amp-list>
- <amp-live-list>
- <amp-social-share>
Максимальная высота боковой панели, заданная по умолчанию при помощи свойства CSS max-height, – 100vh. Если указано большее значение, появляется вертикальная полоса прокрутки. Значение можно переопределить в стилях CSS.
Ширину боковой панели можно задать и изменить, используя стили CSS (минимальная ширина – 45px).
Масштабирование жестами отключено для компонента amp-sidebar и его маски, когда боковая панель открыта.

Пример

В этом примере amp-sidebar содержит элементы навигации. При этом второй и четвертый из них, Nav Item 2 и Nav Item 4, связаны с имеющимися на странице идентификаторами элементов. Используя атрибут on, мы обеспечиваем прокрутку страницы до нужного элемента, идентификатор которого вместе с методом scrollTo указывается в значении атрибута.

<amp-sidebar id="sidebar1" layout="nodisplay" side="right">
  <ul>
    <li>Nav item 1</li>
    <li><a href="#idTwo" on="tap:idTwo.scrollTo">Nav item 2</a></li>
    <li>Nav item 3</li>
    <li><a href="#idFour" on="tap:idFour.scrollTo">Nav item 4</a></li>
    <li>Nav item 5</li>
    <li>Nav item 6</li>
  </ul>
</amp-sidebar>

Открытие и закрытие боковой панели

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

Действие	Описание
open (по умолчанию)	Открывает боковую панель.
close	Закрывает боковую панель.
toggle	Открывает панель, если она была скрыта, и наоборот.

Если пользователь коснется частично видимой области с основным контентом, боковая панель закроется.

Ещё один способ скрыть панель – нажать клавишу Esc на клавиатуре.

Пример

<button class="hamburger" on='tap:sidebar1.toggle'></button>
<button on='tap:sidebar1'>Open</button>
<button on='tap:sidebar1.open'>Open</button>
<button on='tap:sidebar1.close'>x</button>

Панель инструментов

Чтобы создать панель инструментов (toolbar) в разделе <body>, добавьте в <amp-sidebar> дочерний элемент <nav>, а в нем укажите атрибут toolbar с запросом медиа и атрибут toolbar-target с идентификатором какого-либо элемента на странице. Принцип действия toolbar заключается в том, что <nav> со своими дочерними элементами копируется и прибавляется к элементу, указанному в значении атрибута toolbar-target.

Принципы работы

Из боковой панели получится панель инструментов, если добавить элемент nav с атрибутами toolbar и toolbar-target.
Элемент nav должен быть дочерним по отношению к <amp-sidebar>. Следует придерживаться такого формата: <nav toolbar="(media-query)" toolbar-target="elementID">.
- Пример правильного использования: <nav toolbar="(max-width: 1024px)" toolbar-target="target-element">.
В контейнере nav с атрибутом toolbar должен содержаться только один элемент <ul> с дочерними элементами <li>.
- В элементы <li> можно включить любые допустимые элементы HTML (из числа поддерживаемых на AMP-страницах) или элементы AMP, поддерживаемые компонентом <amp-sidebar>.
Панель инструментов работает, только пока действителен запрос медиа в атрибуте toolbar. Кроме того, обязательно наличие на странице элемента с идентификатором, указанным в значении атрибута toolbar-target.

Пример простой панели инструментов

В этом примере приводится панель инструментов (toolbar) для показа в окне шириной не более 767 пикселей. Панель инструментов содержит элемент input с текстовой подсказкой для ввода данных. Содержание toolbar будет добавлено к элементу <div id="target-element">.

<amp-sidebar id="sidebar1" layout="nodisplay" side="right">
  <ul>
    <li>Nav item 1</li>
    <li><a href="#idTwo" on="tap:idTwo.scrollTo">Nav item 2</a></li>
    <li>Nav item 3</li>
    <li><a href="#idFour" on="tap:idFour.scrollTo">Nav item 4</a></li>
    <li>Nav item 5</li>
    <li>Nav item 6</li>
  </ul>

  <nav toolbar="(max-width: 767px)" toolbar-target="target-element">
    <ul>
      <li>
        <input placeholder="Найти..."/>
      </li>
    </ul>
  </nav>
</amp-sidebar>

<div id="target-element">
</div>

Оформление панели инструментов с помощью стилей

Классы будут применяться к панели инструментов toolbar в элементе <amp-sidebar> в зависимости от того, показан или скрыт элемент toolbar-target. Такой прием полезен при назначении разных стилей элементам toolbar и toolbar-target. Используемые классы – amp-sidebar-toolbar-target-shown и amp-sidebar-toolbar-target-hidden. Класс amp-sidebar-toolbar-target-shown применяется к элементу toolbar, когда элемент toolbar-target отображен. Класс amp-sidebar-toolbar-target-hidden применяется к элементу toolbar, когда элемент toolbar-target скрыт.

Пример с классами состояния панели инструментов

В этом примере приводится панель инструментов (toolbar) для показа в окне шириной не более 767px. Панель инструментов содержит элемент input с текстовой подсказкой для ввода данных. Содержание toolbar будет добавлено к элементу <div id="target-element">. Однако теперь мы включили в код специальные стили, чтобы скрывать элемент toolbar, когда показывается элемент <div id="target-element">.

<style amp-custom="">

  .amp-sidebar-toolbar-target-shown {
      display: none;
  }

</style>

<amp-sidebar id="sidebar1" layout="nodisplay" side="right">
  <ul>
    <li>Nav item 1</li>
    <li><a href="#idTwo" on="tap:idTwo.scrollTo">Nav item 2</a></li>
    <li>Nav item 3</li>
    <li><a href="#idFour" on="tap:idFour.scrollTo">Nav item 4</a></li>
    <li>Nav item 5</li>
    <li>Nav item 6</li>
  </ul>

  <nav toolbar="(max-width: 767px)" toolbar-target="target-element">
    <ul>
      <li>
        <input placeholder="Найти..."/>
      </li>
    </ul>
  </nav>
</amp-sidebar>

<div id="target-element">
</div>

Посмотрите интерактивные примеры на сайте AMP By Example.

Боковая панель для AMP-историй

Боковую панель amp-sidebar можно использовать в компоненте amp-story.

Принципы работы

Элемент <amp-sidebar> следует включить непосредственно в <amp-story>.
По умолчанию боковая панель показывается в обычных AMP-документах с правой стороны, если язык страницы предполагает чтение слева направо, и с левой стороны, если язык страницы предполагает чтение справа налево.
Цвет фона у элемента <amp-sidebar> по умолчанию белый. Его можно изменить в стилях CSS.
Максимальная ширина боковой панели <amp-sidebar> не будет превышать 280px, а на компьютерах – 320px.
В интерфейсе истории появляется кнопка в виде трех горизонтальных линий, с помощью которой можно открывать и закрывать боковую панель.

Чтобы в интерфейсе историй не возникало несоответствий, список допустимых атрибутов и функций ограничен. Ниже перечислены атрибуты и функции, которые разрешается применять в элементе amp-sidebar внутри amp-story.

Пример простой боковой панели в AMP-истории

В этом примере показан простой компонент amp-sidebar в amp-story.

...
<body>
  <amp-story standalone>
  <amp-sidebar id="sidebar1" layout="nodisplay">
    <ul>
      <li><a href="https://amp.dev"> External Link </a></li>
      <li>Nav item 2</li>
      <li>Nav item 3</li>
    </ul>
  </amp-sidebar>
  <amp-story-page id="cover">
    <amp-story-grid-layer template="fill">
      <h1>Hello World</h1>
      <p>This is the cover page of this story.</p>
    </amp-story-grid-layer>
  </amp-story-page>
  ...
</body>

Атрибуты

side

Определяет, с какой стороны страницы будет открываться боковая панель: с левой (left) или с правой (right). Если не указать сторону, значение атрибута side будет унаследовано от атрибута dir в теге body (ltr => left, rtl => right). В случае отсутствия атрибута dir атрибуту side по умолчанию присваивается значение left.

layout

Определяет тип макета при показе боковой панели. У этого атрибута должно быть значение nodisplay.

open

Этот атрибут присутствует, когда боковая панель открыта.

data-close-button-aria-label

Необязательный атрибут, при помощи которого задается текст ярлыка ARIA для кнопки закрытия. Это дополнительный способ указать на ее назначение.

Этот атрибут присутствует в дочернем элементе <nav toolbar="(media-query)" toolbar-target="elementID">. Допустимое значение – запрос медиа, определяющий, когда показывать панель инструментов. Более подробная информация об использовании панелей инструментов приведена выше в соответствующем разделе.

Этот атрибут присутствует в дочернем элементе <nav toolbar="(media-query)" toolbar-target="elementID"> и принимает в качестве значения идентификатор того или иного элемента на странице. Атрибут toolbar-target предназначен для того, чтобы панель инструментов без заданных по умолчанию стилей вставлялась на место указанного идентификатора. Более подробная информация об использовании панелей инструментов приведена выше в соответствующем разделе.

универсальные атрибуты

Атрибуты, которые поддерживаются большинством компонентов AMP.

Поддержка стилей

Компонент amp-sidebar совместим со стандартными стилями CSS.

Можно настроить автоматическую корректировку ширины (width) боковой панели amp-sidebar – от 45px (по умолчанию) до 80vw.
Можно настроить автоматическую корректировку высоты amp-sidebar. Если высота окажется больше 100vw, у боковой панели появится вертикальная полоса прокрутки. Высота по умолчанию – 100vw. Ее можно уменьшить в стилях CSS.
Текущее состояние боковой панели определяется по атрибуту open, который появляется в теге amp-sidebar, когда она открыта на странице.

На сайте AMP Start вы найдете уже оформленные меню навигации с адаптивным макетом. Можете добавлять их на свои AMP-страницы.

Автоматическая прокрутка в контейнерах, содержание которых выходит за границы видимой области

Компонент amp-sidebar в двух своих разновидностях (боковая панель и панель инструментов) поддерживает автоматическую прокрутку контейнера до первого элемента с атрибутом autoscroll.

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

В случае использования панели инструментов toolbar атрибут autoscroll работает только при условии, что для элемента <nav toolbar> задано правило CSS overflow: auto или overflow: scroll.

<style amp-custom="">

  nav [toolbar] {
    overflow: auto;
  }

</style>

<amp-sidebar id="sidebar1" layout="nodisplay" side="right">
  <nav toolbar="(max-width: 767px)" toolbar-target="target-element">
    <ul>
      <li>Nav item 1</li>
      <li>Nav item 2</li>
      <li>Nav item 3</li>
      <li autoscroll class="currentPage">Nav item 4</li>
      <li>Nav item 5</li>
      <li>Nav item 6</li>
    </ul>
  </nav>
</amp-sidebar>

<div id="target-element">
</div>

В этом файле представлен пример рабочего кода.

Удобство просмотра

Внедряя <amp-sidebar>, помните, что пользователи часто будут открывать ваши страницы на мобильных устройствах в средстве просмотра AMP, где может отображаться заголовок с фиксированной позицией. Браузеры нередко добавляют второй подобный заголовок вверху страницы. Ещё один фиксированный элемент там же займет на экране мобильного устройства много места и при этом не будет содержать новой для пользователя информации.

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

Валидация

С правилами для компонента amp-sidebar можно ознакомиться в спецификации валидатора AMP.

Need more help?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow

Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub