Краткое руководство: добавление элемента ListView (HTML)
[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. В случае разработки приложений для Windows 10 см. раздел последняя документация]
Большинство приложений отображают какие-либо списки данных, например адресную книгу, коллекцию изображений или входящие сообщения почты. Информация для списков может загружаться из базы данных, Интернета или других источников в формате JSON. Библиотека WinJS содержит элемент управления ListView, который оптимально подходит для предоставления такой информации.
Предварительные требования
Вы должны уметь создавать простое приложение среды выполнения Windows на JavaScript с использованием элементов управления WinJS. Инструкции для начала работы с элементами управления из библиотеки WinJS см. в статье Краткое руководство: добавление элементов управления и стилей WinJS.
Что такое ListView?
ListView — это элемент управления WinJS, который представляет данные из IListDataSource в виде настраиваемого списка или сетки. WinJS предоставляет несколько типов объектов IListDataSource:
- Вы можете использовать List для создания IListDataSource из массива данных.
- В то время как StorageDataSource используется для доступа к сведениям о файлах и папках.
Вы также можете создать собственный источник и подключить его к другим поставщикам данных, например к веб-службе или базе данных. Соответствующие инструкции см. в руководстве Создание собственного источника данных.
Создание элемента ListView
Для создания элемента ListView:
Добавьте ссылки на библиотеку WinJS в ваш HTML-файл, если их там еще нет.
Использование последней версии WinJS:
- Скачайте последнюю версию по ссылке Скачать WinJS и скопируйте ее в каталог своего приложения или веб-сайта.
- Добавьте WinJS CSS и ссылки на сценарии на каждую страницу своего приложения или веб-сайта, использующую возможности WinJS.
<!-- WinJS references --> <link href="/WinJS/css/ui-dark.css" rel="stylesheet"> <script src="/WinJS/js/WinJS.js"></script>
В этом примере приведен HTML-код файла default.html, сгенерированного при создании нового проекта Пустое приложение в Microsoft Visual Studio.
<!-- default.html --> <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>ListViewExample</title> <!-- WinJS references --> <link href="/WinJS/css/ui-dark.css" rel="stylesheet"> <script src="/WinJS/js/WinJS.js"></script> <!-- ListViewExample references --> <link href="/css/default.css" rel="stylesheet"> <script src="/js/default.js"></script> </head> <body> <p>Content goes here</p> </body> </html>
Создайте в своем HTML-файле элемент div и задайте для его свойства data-win-control значение
WinJS.UI.ListView
.<div id="basicListView" data-win-control="WinJS.UI.ListView"> </div>
В связанном с HTML-файлом коде JavaScript добавьте вызов функции WinJS.UI.processAll при загрузке этого файла.
WinJS.UI.processAll();
В следующем примере приведено содержимое файла default.js, связанного с default.html, который был сгенерирован при создании проекта Пустое приложение.
(function () { "use strict"; var app = WinJS.Application; var activation = Windows.ApplicationModel.Activation; WinJS.strictProcessing(); app.onactivated = function (args) { if (args.detail.kind === activation.ActivationKind.launch) { if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) { // TODO: This application has been newly launched. Initialize // your application here. } else { // TODO: This application has been reactivated from suspension. // Restore application state here. } args.setPromise(WinJS.UI.processAll()); } }; app.oncheckpoint = function (args) { // TODO: This application is about to be suspended. Save any state // that needs to persist across suspensions here. You might use the // WinJS.Application.sessionState object, which is automatically // saved and restored across suspension. If you need to complete an // asynchronous operation before your application is suspended, call // args.setPromise(). }; app.start(); })();
Для корректной работы примера элемент ListView должен находиться на начальной странице (default.html). При добавлении ListView в элемент управления Page вызывать функцию WinJS.UI.processAll не требуется, так как элемент управления Page делает это самостоятельно. Если вы добавляете ListView в собственный пользовательский HTML, вы можете использовать событие DOMContentLoaded для вызова WinJS.UI.processAll. Дополнительные сведения об активации элементов управления см. в разделе Краткое руководство: добавление элементов управления и стилей WinJS.
Этот код создает пустой ListView. При запуске приложения отобразится окно без каких-либо данных. В следующем разделе будет показано, как внести в ListView данные.
Добавление данных
Для удобства исходный код источника данных лучше всего поместить в отдельный JavaScript-файл. В этом разделе вы узнаете, как создать для своих данных JavaScript-файл и List, а также как с помощью функции WinJS.Namespace.define открыть доступ к данным всем остальным компонентам приложения.
Для добавления файла данных в проект используйте Visual Studio. В окне "Обозреватель решений" щелкните правой кнопкой мыши папку проекта
js
и выберите команду Добавить > Новый элемент. Откроется диалоговое окно Добавление нового элемента.Выберите Файл JavaScript. Назовите его "dataExample.js". Чтобы создать файл, нажмите кнопку Добавить. Visual Studio создает пустой файл JavaScript с именем dataExample.js.
Откройте файл dataExample.js. Создайте анонимную функцию и включите строгий режим.
Как упоминалось в статье Создание простейших приложений, хорошим тоном в программировании считается инкапсуляция кода на JavaScript заключением его в анонимную функцию, при этом рекомендуется применение строгого режима.
(function () { "use strict"; })();
Создайте массив данных. В данном примере будет создан массив объектов. Каждый из объектов имеет три свойства: заголовок, текст и изображение.
(function () { "use strict"; var dataArray = [ { title: "Basic banana", text: "Low-fat frozen yogurt", picture: "images/60banana.png" }, { title: "Banana blast", text: "Ice cream", picture: "images/60banana.png" }, { title: "Brilliant banana", text: "Frozen custard", picture: "images/60banana.png" }, { title: "Orange surprise", text: "Sherbet", picture: "images/60orange.png" }, { title: "Original orange", text: "Sherbet", picture: "images/60orange.png" }, { title: "Vanilla", text: "Ice cream", picture: "images/60vanilla.png" }, { title: "Very vanilla", text: "Frozen custard", picture: "images/60vanilla.png" }, { title: "Marvelous mint", text: "Gelato", picture: "images/60mint.png" }, { title: "Succulent strawberry", text: "Sorbet", picture: "images/60strawberry.png" } ]; })();
Примечание С помощью данного кода можно поменять рисунки к файлам на локальном компьютере или получить рисунки, скачав Начало работы с примерами использования ListView (это не один и тот же пример, но в нем использованы те же рисунки). Пример все еще будет выполняться без добавления изображений.
Создайте объект List с помощью массива.
(function () { "use strict"; var dataArray = [ { title: "Basic banana", text: "Low-fat frozen yogurt", picture: "images/60banana.png" }, { title: "Banana blast", text: "Ice cream", picture: "images/60banana.png" }, { title: "Brilliant banana", text: "Frozen custard", picture: "images/60banana.png" }, { title: "Orange surprise", text: "Sherbet", picture: "images/60orange.png" }, { title: "Original orange", text: "Sherbet", picture: "images/60orange.png" }, { title: "Vanilla", text: "Ice cream", picture: "images/60vanilla.png" }, { title: "Very vanilla", text: "Frozen custard", picture: "images/60vanilla.png" }, { title: "Marvelous mint", text: "Gelato", picture: "images/60mint.png" }, { title: "Succulent strawberry", text: "Sorbet", picture: "images/60strawberry.png" } ]; var dataList = new WinJS.Binding.List(dataArray); })();
Предоставьте List, описав пространство имен и добавив List в качестве открытого члена.
Поскольку написанный код заключен в анонимную функцию, ни один его фрагмент не открыт для общего доступа. Сохранение конфиденциальности данных — одна из причин использования анонимной функции. Чтобы ваш ListView получил доступ к List, вы должны открыть к нему общий доступ. Одним из способов сделать это является использование функции WinJS.Namespace.define для создания пространства имен и добавления List в качестве одного из его членов.
Функция WinJS.Namespace.define принимает два параметра: имя создаваемого пространства имен и объект, содержащий одну или несколько пар свойство-значение. Каждое свойство — это открытое имя члена, а каждое значение — это базовая переменная, свойство или функция в вашем частном коде, к которым вы хотите открыть доступ.
Данный пример создает пространство имен, названное DataExample, которое предоставляет открытый член, названный itemList, возвращающий ваш List.
(function () { "use strict"; var dataArray = [ { title: "Basic banana", text: "Low-fat frozen yogurt", picture: "images/60banana.png" }, { title: "Banana blast", text: "Ice cream", picture: "images/60banana.png" }, { title: "Brilliant banana", text: "Frozen custard", picture: "images/60banana.png" }, { title: "Orange surprise", text: "Sherbet", picture: "images/60orange.png" }, { title: "Original orange", text: "Sherbet", picture: "images/60orange.png" }, { title: "Vanilla", text: "Ice cream", picture: "images/60vanilla.png" }, { title: "Very vanilla", text: "Frozen custard", picture: "images/60vanilla.png" }, { title: "Marvelous mint", text: "Gelato", picture: "images/60mint.png" }, { title: "Succulent strawberry", text: "Sorbet", picture: "images/60strawberry.png" } ]; var dataList = new WinJS.Binding.List(dataArray); // Create a namespace to make the data publicly // accessible. var publicMembers = { itemList: dataList }; WinJS.Namespace.define("DataExample", publicMembers); })();
Итак, мы создали источник данных, к которому имеет доступ ListView. Теперь нужно подключить эти данные к ListView.
Подключение данных к ListView
В разделе head HTML-файла, содержащего элемент ListView, добавьте ссылку на только что созданный файл данных (dataExample.js):
<head> <!-- Other file references ... --> <!-- Your data file. --> <script src="/js/dataExample.js"></script> </head>
Используйте данные, созданные в последнем разделе, чтобы задать элементу управления ListView свойство itemDataSource.
Свойство itemDataSource принимает объект IListDataSource. Объект List не является IListDataSource, но имеет свойство dataSource, которое возвращает IListDataSource версию самого себя.
Чтобы подключить свои данные, задайте ListView элементу управления itemDataSource свойство
DataExample.itemList.dataSource
:<div id="basicListView" data-win-control="WinJS.UI.ListView" data-win-options="{ itemDataSource : DataExample.itemList.dataSource }"> </div>
Запустите приложение. В ListView отобразятся свойства и значения, взятые из источника данных.
Однако это не совсем тот результат, который мы ожидали. Нужно, чтобы показывались только значения заголовка и текстового поля, а также чтобы на экране были сами изображения, а не пути к ним. Для решения проблемы необходимо определить шаблон Template. Подробнее об этом — в следующем подразделе.
Определение шаблона элемента
Итак, в элементе ListView есть все необходимые данные, но пока что они отображаются некорректно. Для этого потребуется шаблон элемента, содержащий разметку, которую вам необходимо использовать для отображения каждого элемента в списке. Шаблон элемента может содержать множество других элементов управления (подробнее см. в разделе Добавление интерактивных элементов), кроме FlipView или другого элемента ListView.
Это можно сделать двумя способами: определить WinJS.Binding.Template с помощью ручной разметки или же реализовать функцию, которая сделает это автоматически. В этом примере мы создадим шаблон вручную. Информацию о создании функции для разметки см. в справке к свойству itemTemplate.
Создать WinJS.Binding.Template довольно легко — достаточно задать разметку для каждого элемента списка и указать местоположение каждого поля данных в окне приложения.
В HTML-файле создайте элемент управления WinJS.Binding.Template и присвойте ему идентификатор. Этот пример использует шаблон идентификатора "mediumListIconTextTemplate".
<div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template"> </div>
Примечание Прежде чем применять шаблон, его необходимо определить. Добавьте HTML-код шаблона перед кодом ListView.
В WinJS.Binding.Template должен быть только один корневой элемент. Создайте div-элемент, который будет родительским объектом для содержимого шаблона.
<div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template"> <div> </div> </div>
Создайте разметку, которую ListView будет применять ко всем внутренним элементам данных. Данные, полученные на предыдущем шаге, включают в себя путь к изображению, заголовок и несколько строк текста, поэтому создадим следующие элементы:
- img — для поля с картинкой;
- h4 — для поля заголовка;
- h6 — для текстового поля.
<div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template"> <div> <!-- Displays the "picture" field. --> <img src="#" /> <div> <!-- Displays the "title" field. --> <h4></h4> <!-- Displays the "text" field. --> <h6></h6> </div> </div> </div>
Чтобы избежать проблем с макетом, нужно всегда указывать размеры как корневого элемента шаблона, так и его внутренних элементов img.
<div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template"> <div style="width: 150px; height: 100px;"> <!-- Displays the "picture" field. --> <img src="#" style="width: 60px; height: 60px;" /> <div> <!-- Displays the "title" field. --> <h4></h4> <!-- Displays the "text" field. --> <h6></h6> </div> </div> </div>
Установите атрибут data-win-bind на каждом элементе, который отображает данные. Атрибут data-win-bind использует синтаксис:
data-win-bind="propertyName: dataFieldName"
Например, чтобы привязать свойство src объекта img к полю "рисунка", используйте синтаксис:
<img data-win-bind="src : picture" />
Если нужно задать несколько свойств, разделяйте их точкой с запятой:
data-win-bind="property1Name: dataField1Name; property2Name: dataField2Name"
В этом примере элементы шаблона привязываются к соответствующим полям данных.
<div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template"> <div style="width: 150px; height: 100px;"> <!-- Displays the "picture" field. --> <img src="#" style="width: 60px; height: 60px;" data-win-bind="alt: title; src: picture" /> <div> <!-- Displays the "title" field. --> <h4 data-win-bind="innerText: title"></h4> <!-- Displays the "text" field. --> <h6 data-win-bind="innerText: text"></h6> </div> </div> </div>
Чтобы применить шаблон элемента, используйте синтаксис select для задания свойства itemTemplate объекта ListView вашему шаблону элемента.
<div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template"> <div style="width: 150px; height: 100px;"> <!-- Displays the "picture" field. --> <img src="#" style="width: 60px; height: 60px;" data-win-bind="alt: title; src: picture" /> <div> <!-- Displays the "title" field. --> <h4 data-win-bind="innerText: title"></h4> <!-- Displays the "text" field. --> <h6 data-win-bind="innerText: text"></h6> </div> </div> </div> <div id="basicListView" data-win-control="WinJS.UI.ListView" data-win-options="{itemDataSource : DataExample.itemList.dataSource, itemTemplate: select('#mediumListIconTextTemplate')}"> </div>
Запустите приложение. В списке появятся соответствующие данные.
Применение стилей к ListView
Элемент ListView не подгоняет динамически свою высоту под размер содержимого. Поэтому для отображения ListView необходимо указывать его абсолютную высоту. Таблицы стилей WinJS задают высоту элемента управления ListView 400 пикселей, но вы легко можете задать другую высоту, переопределив стиль по умолчанию с помощью собственной CSS. Добавьте свою CSS в CSS-файл приложения, чтобы указать высоту и ширину элемента ListView, а также задать толщину его рамки:
Задание стиля ListView для Windows
.win-listview
{
height: 500px;
width: 500px;
border: 2px solid gray;
}
Задание стиля ListView для Windows Phone 8.1
.win-listview
{
height: 400px;
width: 300px;
border: 2px solid gray;
}
Для применения стилей к ListView используется класс WinJS win-listview. В приведенном примере каждому элементу ListView присваиваются новые значения высоты, ширины и рамки. Чтобы просто изменить один объект ListView, добавьте идентификатор элемента управления ListView главного элемента div к селектору:
Задание специального стиля ListView для Windows
#basicListView .win-listview
{
height: 500px;
width: 500px;
border: 2px solid gray;
}
Задание специального стиля ListView для Windows Phone 8.1
#basicListView .win-listview
{
height: 400px;
width: 300px;
border: 2px solid gray;
}
Запустите приложение. Теперь в ListView нормально помещаются все элементы.
Таблицы стилей WinJS определяют классы CSS, которые вы можете переопределить, чтобы настроить внешний вид и сделать удобным использование элемента управления библиотеки WinJS. Классы CSS, которые вы используете с ListView, включают в себя:
win-listview
Стили CSS для самого ListView.
win-container
Стили для ListView или для контейнера элементов FlipView. Каждый элемент имеет свой собственный контейнер.
win-progress
Стили для индикатора хода выполнения, который показывает, когда объект ListView выполняет загрузку элементов.
Полный список классов приведен в ListView reference page.
В этом примере определяется стиль, который добавляет поля вокруг каждого контейнера элементов в ListView.
#basicListView .win-listview .win-container {
margin: 10px;
}
Следующий пример задает внешний вид элементов списка ListView при наведении указателя мыши.
#basicListView .win-listview .win-container:hover {
color: red;
}
Примечание
Элемент ListView поддерживает левое, верхнее и нижнее поля, но у него не может быть правого поля. Возможное решение проблемы — добавить элемент, равный по ширине соответствующему полю, и определить его стиль. Например, задайте свойству visibility этого элемента значение "none", а затем вставьте его справа от ListView.
Применение стилей к элементам
В предшествующих примерах были использованы встроенные стили и классы WinJS, чтобы применить стили к вашему объекту ListView и его элементам. Однако CSS-классы можно применять и к шаблону элемента. В следующем примере показано, как обновить шаблон, который был создан в разделе Определение шаблона элемента. Мы удалим встроенные стили и вместо них добавим CSS-классы.
<div id="mediumListIconTextTemplate"
data-win-control="WinJS.Binding.Template"
style="display: none">
<div class="mediumListIconTextItem">
<img src="#" class="mediumListIconTextItem-Image" data-win-bind="src: picture" />
<div class="mediumListIconTextItem-Detail">
<h4 data-win-bind="innerText: title"></h4>
<h6 data-win-bind="innerText: text"></h6>
</div>
</div>
</div>
Вставьте в CSS-файл приложения следующие стили:
.mediumListIconTextItem
{
width: 282px;
height: 70px;
padding: 5px;
overflow: hidden;
display: -ms-grid;
}
.mediumListIconTextItem img.mediumListIconTextItem-Image
{
width: 60px;
height: 60px;
margin: 5px;
-ms-grid-column: 1;
}
.mediumListIconTextItem .mediumListIconTextItem-Detail
{
margin: 5px;
-ms-grid-column: 2;
}
Теперь ListView выглядит вот так:
Как правило, создавать собственные стили шаблонов не требуется. Перечень часто используемых шаблонов и их CSS приведен в разделах Шаблоны элементов для макетов списка и Шаблоны элементов для макетов сетки.
Переключение между макетами списка, сетки и ячеек
У элемента ListView есть три макета — для списка, сетки и ячейки.
Чтобы использовать макет списка, задайте для свойства layout значение WinJS.UI.ListLayout, как показано здесь:
<div id="basicListView" data-win-control="WinJS.UI.ListView" data-win-options="{ itemDataSource : DataExample.itemList.dataSource, itemTemplate: select('#mediumListIconTextTemplate'), layout: {type: WinJS.UI.ListLayout}}"> </div>
Чтобы использовать макет сетки, задайте для свойства layout значение WinJS.UI.GridLayout, как показано здесь:
<div id="basicListView" data-win-control="WinJS.UI.ListView" data-win-options="{ itemDataSource : DataExample.itemList.dataSource, itemTemplate: select('#mediumListIconTextTemplate'), layout: {type: WinJS.UI.GridLayout}}"> </div>
(Только для Windows) Чтобы использовать макет ячейки, задайте для свойства макета значение WinJS.UI.CellSpanningLayout, как показано здесь:
<div id="basicListView" data-win-control="WinJS.UI.ListView" data-win-options="{ itemDataSource : DataExample.itemList.dataSource, itemTemplate: select('#mediumListIconTextTemplate'), layout: {type: WinJS.UI.CellSpanningLayout}}"> </div>
Макет ListView можно изменить в любое время, даже после того, как элемент создан.
Группировка данных
В вашем объекте ListView можно группировать элементы. На этой иллюстрации показаны элементы, сгруппированные в алфавитном порядке:
Подробнее об этом см. в разделе Группировка элементов в ListView.
Добавление интерактивных элементов в шаблон элементов
Примечание Шаблон элементов может содержать множество других элементов управления, кроме FlipView или другого элемента ListView.
Выбор и вызов элементов ListView
Обычно во время взаимодействия пользователя с элементом ListView перехватывает это взаимодействие, чтобы определить, выбрал или вызвал пользователь элемент либо сдвигает все элементы. Чтобы интерактивный элемент, такой как элемент управления, принимал ввод, вы должны присоединить класс CSS win-interactive
к интерактивному элементу или одному из его родительских элементов. Этот элемент и его дочерние элементы получают взаимодействие и больше не запускают события для ListView.
При подключении класса win-interactive
к элементу в шаблоне элементов, убедитесь, что элемент полностью не заполнен, в противном случае, пользователь не сможет ни выбрать, ни вызвать этот элемент.
Чтобы добавлять интерактивные элементы в шаблон элемента, рекомендуется использовать функцию создания шаблона вместо WinJS.Binding.Template. Дополнительные сведения о функциях шаблона см. в разделе Создание функции шаблонов.
Добавление функций упорядочивания и перетаскивания в ListView (только для Windows)
Элемент управления ListView позволяет пользователю упорядочивать и перетаскивать отдельные элементы. Например, можно объявить функцию перетаскивания, установив для свойства itemsDraggable элемента ListView значение "true". Точно так же, чтобы дать пользователю возможность упорядочивать элементы в элементе управления ListView, для свойства itemsReorderable элемента ListView задается значение "true".
<div id="basicListView"
data-win-control="WinJS.UI.ListView"
data-win-options="{ itemDataSource : DataExample.itemList.dataSource,
itemTemplate: select('#mediumListIconTextTemplate'),
itemsDraggable: true,
itemsReorderable: true }">
</div>
Свойство itemsDraggable позволяет видимо перетаскивать отдельные элементы из элемента управления ListView. Когда пользователь начинает перетаскивать элемент из ListView, возникает событие itemdragstart. (Это событие также возникает в начале операции упорядочивания.) Когда элемент перемещается в ListView, ListView вызывает событие itemdragdrop.
Дополнительные сведения о добавлении функций перетаскивания и упорядочения в элемент управления ListView см. инструкции по включению перетаскивания и упорядочения для ListView или скачайте пример перетаскивания и упорядочения в HTML ListView.
Примеры использования ListView
Наглядные примеры кода практически каждого элемента управления WinJS и онлайн-редактора см. по ссылке try.buildwinjs.com.
Эти дополнительные примеры помогут вам более подробно изучить возможности элемента управления ListView.
- Начало работы с примерами использования ListView
- Пример шаблона элемента ListView
- Пример группировки в ListView и контекстного масштабирования
- Пример StorageDataSource и GetVirtualizedFilesVector
Краткая сводка и дальнейшие действия
Вы научились создавать элемент ListView и привязывать к нему данные. Также вы узнали, как создавать шаблоны элемента и применять к нему стили.
Перечень предопределенных шаблонов, которые вы можете использовать в своих приложениях, приведен в разделах Шаблоны элементов для макетов списка и Шаблоны элементов для макетов сетки. Подробнее о группировке элементов см. в разделе Группировка элементов в ListView.