Список виджет

Основные списки с ссылками

Список с отображением элементов кодируется как простой неупорядоченный список, содержащий элементы списка с ссылкой с атрибутом data-role="listview". jQuery Mobile применит все необходимые стили для преобразования списка в удобный для мобильных устройств список с индикатором стрелки вправо, занимающий всю ширину окна браузера. При нажатии на элемент списка фреймворк запустит клик по первой ссылке внутри элемента списка, отправит запрос Ajax для URL в ссылке, создаст новую страницу в DOM, а затем инициирует переход к странице. Посмотрите ссылку на атрибуты данных, чтобы увидеть все возможные атрибуты, которые можно добавить в списки с отображением элементов.

Вот разметка HTML для простого списка с ссылками.

<ul data-role="listview">
  <li><a href="acura.html">Acura</a></li>
  <li><a href="audi.html">Audi</a></li>
  <li><a href="bmw.html">BMW</a></li>
</ul>

• ui-listview: Внешний контейнер для виджета списка с отображением элементов
  • ui-listview-item-static: Простейший элемент списка списка с отображением элементов, когда внутри элемента нет вложенных тегов
  • ui-listview-item-divider: Элемент списка, являющийся разделителем
  • ui-listview-item-has-alternate: Элемент списка, содержащий более одного тега
    • ui-listview-item-button: Первый элемент
    • ui-listview-item-split-button: Последний элемент
      • ui-listview-item-split-icon: Иконка последнего элемента
  • ui-listview-item: Элемент списка, содержащий только один элемент . Если элемент списка с отображением элементов имеет числовой индикатор, он дополнительно будет иметь класс ui-listview-item-has-count.
    • ui-listview-item-button: Элемент элемента списка
    • ui-listview-item-icon: Иконка для элемента списка
    • ui-listview-item-count-bubble: Числовой индикатор для элемента списка, если присутствует

Примечание о списках без отступов: все стандартные списки без отступов имеют отступ -1em (16px) для компенсации отступа 1em в области содержимого, чтобы списки простирались до краев экрана. Если вы добавляете другие виджеты над или под списком, отрицательный отступ может привести к наложению этих элементов, поэтому вам потребуется добавить дополнительное пространство в вашем пользовательском CSS.

Нумерованные списки

Списки также могут быть созданы из упорядоченных списков (ol), что полезно при представлении элементов в последовательности, таких как результаты поиска или очередь фильмов. При применении расширенной разметки к списку с отображением элементов jQuery Mobile попытается сначала использовать CSS для добавления номеров в список, а в случае отсутствия поддержки вернётся к вставке номеров с помощью JavaScript.

Только для чтения списки

Списки с отображением элементов также могут использоваться для отображения неинтерактивного списка элементов, обычно как вложенный список. Этот список создаётся из неупорядоченного или упорядоченного списка, не содержащего элементов списка с ссылкой. Фреймворк стилизует статические элементы списка идентично элементам списка, содержащим ссылки, но статические элементы получают цвет фона тела (ui-body-a) вместо цвета фона кнопки (ui-btn-a).

Списки со разделенными кнопками

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

Иконку правой иконки-разделителя можно задать, указав атрибут data-split-icon в списке с отображением элементов с именем иконки иконки, которую вы хотите. По умолчанию используется иконка "carat-r", но ее можно настроить с помощью splitIcon параметра списка с отображением элементов. Добавив атрибут data-icon к элементу списка, можно задать индивидуальные иконки для каждого разделителя. Цвет темы цветовой палитры разделенной кнопки по умолчанию равен "b" (синий в теме по умолчанию), но его можно задать, указав букву цветовой палитры с атрибутом data-split-theme на уровне списка с отображением элементов или для отдельных разделенных кнопок с атрибутом data-theme на уровне ссылки.

Разделители списка

Элементы списка можно преобразовать в разделители для организации и группирования элементов списка. Это делается путем добавления data-role="list-divider" к любому элементу списка. Эти элементы по умолчанию стилизованы с использованием цветовой палитры разделителей "b" (синий в теме по умолчанию), но вы можете указать тему для разделителей, добавив атрибут data-divider-theme к элементу списка (ul или ol) и указав букву цветовой палитры темы.

Авторазделители

Список с отображением элементов можно настроить на автоматическое создание разделителей для его элементов. Это делается путем добавления атрибута data-autodividers="true" к любому списку с отображением элементов.

По умолчанию текст, используемый для создания разделителей, — это заглавная первая буква текста элемента. В качестве альтернативы вы можете указать текст разделителя, задав параметр autodividersSelector для списка с отображением элементов программно. Например, чтобы добавить пользовательский селектор к элементу с id="mylistview":

$( "#mylistview" ).listview({
  autodividers: true,
 
  // the selector function is passed a <li> element from the listview;
  // it should return the appropriate divider text for that <li>
  // element as a string
  autodividersSelector: function ( li ) {
    var out = /* generate a string based on the content of li */;
    return out;
  }
});

Обратите внимание, что если вы используете отформатированные элементы списка, содержащие плавающий элемент (например, ui-li-aside), этот элемент предшествует своим следующим элементам независимо от порядка в вашей разметке HTML. Это приводит к тому, что первая буква плавающего элемента используется в качестве текста разделителя. Поэтому рекомендуется указать текст разделителя в этом случае.

Если к списку добавляются или удаляются новые элементы списка, разделители не обновляются автоматически: вам следует вызвать refresh() для списка с отображением элементов, чтобы перерисовать авторазделители.

Скрытие разделителей

Расширение списка с отображением элементов hidedividers предоставляет параметр hideDividers. При установке в значение true и вызове .listview( "refresh" ) после скрытия элемента списка путем добавления класса ui-screen-hidden к нему расширение скроет те разделители, за которыми сразу следует другой разделитель.

Фильтр поиска

Начиная с jQuery Mobile 1.4.0, эта функциональность была перенесена в виджет filterable, который предлагает более общее решение.

Примечание: Функции, такие как автоматическое создание текстового поля ввода и специальная обработка разделителей списка с отображением элементов, устарели начиная с версии 1.4.0. В документации для filterable описан путь миграции для списков с отображением элементов.

Фильтр отображения

Функция фильтра отображения позволяет легко создать простую автозамену с локальными данными. Когда у списка с отображением элементов есть атрибут data-filter-reveal="true", все элементы списка с отображением элементов будут автоматически скрываться, когда поле поиска пустое. Атрибут data-filter-placeholder можно добавить для задания текста подсказки для фильтра. Если вам нужно выполнить поиск по большому списку значений, мы предоставляем способ создания фильтра с удалённым источником данных.

Удаленный автозаполнитель со списком с отображением элементов

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

Если у вас небольшой список элементов, вы можете использовать опцию списка с отображением элементов filter reveal для создания автозаполнения с локальными данными списка с отображением элементов.

Города по всему миру

После ввода как минимум трех символов функция автозаполнения отобразит все возможные совпадения.

Форматирование текста и счётчики

Фреймворк включает в себя соглашения о форматировании текста для общих шаблонов списков, таких как заголовок/описание, дополнительная информация и счётчики с помощью семантической разметки HTML.

• Чтобы добавить индикатор подсчёта справа от элемента списка, оберните число в элемент с классом ui-li-count
• Чтобы добавить иерархию текста, используйте заголовки для увеличения начертания текста и абзацы для уменьшения начертания.
• Дополнительную информацию можно добавить справа от каждого элемента списка, обернув содержимое в элемент с классом ui-li-aside

Миниатюры и значки

Чтобы добавить миниатюры слева от элемента списка, просто добавьте изображение внутри элемента списка в качестве первого дочернего элемента. Фреймворк изменит масштаб изображения до 80 пикселей квадрат. Чтобы использовать стандартные значки 16x16 пикселей в элементах списка, добавьте класс ui-li-icon к элементу изображения.

Вложенные списки

Если списки встроены в страницу с другими типами содержимого, вложенный список упаковывает список в блок, который находится внутри области содержимого с небольшим отступом и закругленными углами (управляемыми темой). Добавление атрибута data-inset="true" к списку (ul или ol) применяет внешний вид вложенного списка.

Вызов плагина списка с отображением элементов

Вы можете напрямую вызвать плагин списка с отображением элементов на любом селекторе, как любой плагин jQuery:

$( "#mylist" ).listview();

Обновление списков

Если вы добавляете элементы в список с отображением элементов, вам нужно вызвать метод refresh() для него, чтобы обновить стили. Например:

$( "#mylist" ).listview( "refresh" );

Обратите внимание, что метод refresh() влияет только на новые узлы, добавленные в список. Это сделано для повышения производительности. Любые элементы списка, уже улучшенные, будут проигнорированы процессом обновления. Это означает, что если вы измените содержимое или атрибуты уже улучшенного элемента списка, эти изменения не будут отражены. Если вы хотите обновить элемент списка, замените его новым разметкой перед вызовом обновления.

Если вы хотите изначально скрыть элемент списка, вы можете добавить класс ui-screen-hidden к элементу li. Использование этого класса гарантирует правильное применение стилей углов, а также нижней границы последнего видимого элемента.