Модуль Панель

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

Где размещается разметка панели на странице

Панель должна быть соседним элементом с элементами заголовка, содержимого и подвала внутри страницы jQuery Mobile. Вы можете добавить разметку панели как перед, так и после этих элементов, но не между ними.

Вот пример размещения панели перед заголовком, содержимым и подвалом в порядке исходного кода:

<div data-role="page">
 
  <div data-role="panel" id="mypanel">
    <!-- panel content goes here -->
  </div><!-- /panel -->
 
  <!-- header -->
  <!-- content -->
  <!-- footer -->
 
</div><!-- page -->

В качестве альтернативы, вы можете добавить разметку панели после заголовка, содержимого и подвала в порядке исходного кода, непосредственно перед закрытием контейнера страницы. Где вы разместите разметку панели в исходном коде, будет зависеть от того, как вы хотите, чтобы содержимое страницы читалось людьми, использующими устройство C-класса (только HTML) или с помощью программы чтения экрана.

Если на странице есть панель, фреймворк оборачивает секции заголовка, содержимого и подвала в div. При открытии панели с режимом отображения "reveal" или "push" переход применяется к этому обертыванию. Исключение составляют фиксированные заголовки и подвалы. Они не включаются в обертывание, но будут переходить синхронно с ним. Обратите внимание на то, что все видимое содержимое страницы должно находиться внутри этих секций страницы.

CSS Многоколоночная макетная структура

Чтобы избежать мерцания при открытии панели, мы применяем ускорение аппаратного обеспечения в браузерах WebKit. Используемый CSS может вызывать проблемы с кнопками и элементами форм на странице, если их контейнер имеет многоколоночную макетную структуру CSS (column-count). Чтобы решить эту проблему, вам нужно установить следующее правило для элемента или его контейнера:

-webkit-transform: translate3d( 0, 0, 0 );

Внешние панели

С jQuery Mobile 1.4.0 также стало возможным использовать внешние панели. Это означает, что теперь вы можете размещать панели вне страницы. Внешние панели должны быть инициализированы вручную и не будут обрабатываться автоматической инициализацией. Внешние панели останутся в DOM (если не удалены вручную) до тех пор, пока вы используете навигацию по Ajax, и их можно открывать или закрывать с любой страницы. Это может быть удобно, когда вам нужно использовать одну и ту же панель на нескольких страницах.

Вот пример внешней панели:

<div data-role="page">
  <!-- header -->
  <!-- content -->
  <!-- footer -->
</div><!-- page -->
 
<div data-role="panel" id="mypanel">
  <!-- panel content goes here -->
</div><!-- /panel -->

Панель можно дополнительно улучшить следующим образом:

$( function() {
  $( "#mypanel" ).panel();
} );

Обратите внимание, что если панель содержит другие виджеты jQuery Mobile, такие как списки, их также необходимо инициализировать вручную.

Конвенции разметки панели

Панель состоит из контейнера с атрибутом data-role="panel" и уникальным ID. Этот ID будет ссылаться на ссылку или кнопку для открытия и закрытия панели. Самая базовая разметка панели выглядит следующим образом:

<div data-role="panel" id="mypanel">
  <!-- panel content goes here -->
</div>

Положение панели на экране устанавливается атрибутом data-position. По умолчанию значение left, то есть панель будет отображаться слева от экрана. Укажите data-position="right", чтобы она отображалась справа.

Режим отображения панели устанавливается атрибутом data-display. По умолчанию значение reveal, то есть панель будет находиться под страницей и отображаться, когда страница скроется. Укажите data-display="overlay", чтобы панель отображалась поверх содержимого страницы. Третий режим, data-display="push", анимирует одновременно и панель, и страницу.

Вот пример панели с настраиваемым положением и режимом отображения:

<div data-role="panel" id="mypanel" data-position="right" data-display="push">
  <!-- panel content goes here -->
</div>

Динамическое содержимое

При добавлении динамического содержимого в панель или отображении скрытого содержимого при открытой панели необходимо вызвать событие updatelayout на панели.

$( "#mypanel" ).trigger( "updatelayout" );

Фреймворк проверит новую высоту содержимого панели и в случае, если она превышает высоту экрана, установит высоту страницы min-height на эту высоту и разблокирует панели с data-position-fixed="true". Смотрите также Размещение панели.

Открытие панели

Видимость панели переключается с помощью ссылки на странице или путем непосредственного вызова метода open панели. По умолчанию панель размещается слева в режиме "reveal". Откройте панель программно следующим образом:

$( "#idofpanel" ).panel( "open" , optionsHash );

Для управления панелью из ссылки укажите href на ID нужной панели, которую вы хотите переключить (mypanel в примере ниже). Это указывает фреймворку на привязку ссылки к панели. Эта ссылка будет переключать видимость панели, так что нажатие откроет панель, а повторное нажатие закроет ее.

<a href="#mypanel">Open panel</a>

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

Закрытие панели

Панель можно закрыть, нажав на ссылку, которая ее открыла, проведя пальцем влево или вправо, или нажав клавишу Esc. Чтобы отключить поведение закрытия свайпом, добавьте атрибут data-swipe-close="false" к панели.

По умолчанию панели также могут быть закрыты щелчком вне панели на содержимом страницы. Чтобы предотвратить это поведение, добавьте атрибут data-dismissible="false" к панели. Возможно, на более широких экранах панель и страница будут расположены рядом, а поведение закрытия щелчком по области за пределами панели будет предотвращено только при ширине экрана больше определенной величины, путем применения медиа-запроса. Подробности см. в разделе адаптивности ниже.

Панель также можно закрыть, вызвав метод close панели непосредственно.

$( "#idofpanel" ).panel( "close" );

Часто также добавляют кнопку закрытия внутри панели. Для добавления ссылки, которая закроет панель, добавьте атрибут data-rel="close", чтобы фреймворк закрыл эту панель при нажатии. Важно, чтобы эта ссылка имела смысл и без JavaScript, поэтому мы рекомендуем, чтобы href указывало на ID страницы, на которую пользователь должен перейти при закрытии. Например, если кнопка для открытия панели находится в строке заголовка с ID my-header, ссылка для закрытия в панели должна быть:

<a href="#my-header" data-rel="close">Close panel</a>

Анимации панели

Панели будут анимированы, если браузер поддерживает 3D-преобразования. Наличие такой поддержки определяется теми же критериями, что и поддержка анимации CSS для переходов страниц. Панели используют translateX CSS-преобразования для обеспечения ускорения аппаратного обеспечения и плавности.

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

Опция animate позволяет отключить анимации панелей для всех устройств. Чтобы отключить анимации через разметку, добавьте атрибут data-animate="false" к контейнеру панели.

Инициализация ускорения аппаратного обеспечения происходит при инициализации страницы, чтобы предотвратить мерцание при открытии панели. Поскольку это увеличивает использование памяти, вам необходимо учитывать проблемы производительности, если вы используете длинные списки или скрипты для динамической инъекции содержимого на странице с анимированной панелью.

Размещение панели

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

Вы можете установить для панели position:fixed, чтобы ее содержимое отображалось независимо от того, насколько далеко вы прокрутили страницу, добавив атрибут data-position-fixed="true" к панели. Фреймворк также проверяет, поместится ли содержимое панели в область просмотра, прежде чем применять фиксированное позиционирование, поскольку это свойство предотвратит прокрутку содержимого панели и использование overflow недостаточно поддерживается в настоящее время. Если содержимое панели слишком длинное, чтобы поместиться в область просмотра, фреймворк просто отобразит панель без фиксированного позиционирования.

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

Обратите внимание, что существуют проблемы с фиксированным позиционированием в приложениях Android WebView (не в браузере), которые могут вызвать проблемы с макетом, особенно когда ускорение аппаратного обеспечения не включено. Мы рекомендуем не использовать вариант фиксированной панели при развертывании приложения Android. Кроме того, если у вас есть фиксированная панель на странице с фиксированными инструментальными панелями, инструменты могут не переходить вместе с содержимым страницы.

Стиль панелей

По умолчанию у панелей очень простые стили, чтобы вы могли настроить их по своему усмотрению. Панели по сути представляют собой простые блоки без отступов, расположенные по обе стороны от содержимого страницы. Фреймворк оборачивает содержимое панели в div с классом ui-panel-inner, имеющим отступ 15 пикселей. При необходимости вы можете переопределить это с помощью настраиваемого CSS или использовать опцию classes.panelInner для установки другого имени класса для div.

Панели имеют фиксированную ширину 17em (272 пикселя), что достаточно узко, чтобы при открытии по-прежнему отображать часть содержимого страницы, что упрощает нажатие за пределами панели для закрытия, и выглядит хорошо на широких планшетных или настольных экранах. Стиль для установки ширины панелей довольно сложен, но их можно переопределить с помощью CSS по мере необходимости.

Обратите внимание, что добавление отступов, границ или отступов непосредственно в контейнер панели изменит общие размеры и может повлиять на позиционирование и анимацию. Чтобы избежать этого, применяйте стили к обертывающему элементу содержимого панели (.ui-panel-inner).

Помимо фона темы, ширины и стилей высоты 100%, у панелей очень мало собственных стилей. Тема по умолчанию для панелей — "a". Вы можете установить другую тему для панели, добавив data-theme в контейнер панели или установив data-theme="none" и добавив свои собственные классы для настройки по мере необходимости.

Фреймворк применяет тему, используемую для страницы, к контейнеру содержимого. Перед открытием панели с режимом отображения "reveal" или "push" тема страницы будет установлена в ту же тему, что используется для панели. Это сделано для маскирования того, что большинство мобильных браузеров не завершили рисование фона панели, когда анимация ее открытия уже началась. Если вы используете изображение фона для страницы, вы должны установить его для класса ui-body-* темы, которую вы используете для страницы, чтобы оно использовалось в качестве фона контейнера содержимого.

Адаптивность панели

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

Чтобы страница работала наряду с открытой панелью, ей нужно переформатировать ширину до более узкой, чтобы она поместилась рядом с панелью. Это можно сделать чисто с помощью CSS, добавив левый или правый отступ, равный ширине панели (17em), к содержимому страницы, чтобы заставить переформатировать её. Во-вторых, невидимый слой, размещённый поверх страницы для поведения закрытия по щелчку вне области, скрывается с помощью CSS, поэтому вы можете нажимать на страницу и не закрывать меню.

Вот пример этих правил, заключённых в медиа-запрос, чтобы применить это поведение только выше 35em (560px):

@media (min-width:35em) {
 
  /* wrap on wide viewports once open */
 
  .ui-panel-page-content-open.ui-panel-page-content-position-left {
    margin-right: 17em;
  }
  .ui-panel-page-content-open.ui-panel-page-content-position-right {
    margin-left: 17em;
  }
  .ui-panel-page-content-open {
    width: auto;
  }
 
  /* disable "dismiss" on wide viewports */
  .ui-panel-dismiss {
    display: none;
  }
 
  /* same as the above but for panels with display mode "push" only */
 
  .ui-panel-page-content-open.ui-panel-page-content-position-left.ui-panel-page-content-display-push {
    margin-right: 17em;
  }
  .ui-panel-page-content-open.ui-panel-page-content-position-right.ui-panel-page-content-display-push {
    margin-left: 17em;
  }
  .ui-panel-page-content-open.ui-panel-page-content-display-push {
    width: auto;
  }
 
  .ui-panel-dismiss-display-push {
    display: none;
  }
}

Применение предустановленного разрыва

В стилях виджета есть предустановленный разрыв для этого поведения, который срабатывает при 55em (880px). Этот разрыв не применяется по умолчанию, чтобы вам было проще создавать собственные разрывы, которые лучше всего подходят для вашего контента и дизайна. Чтобы применить предустановленный разрыв, добавьте класс ui-responsive-panel к странице (а не к панели).