WinJS.UI.ListView object

Article
01/26/2017

Displays data items in a customizable list or grid.

Syntax

<div data-win-control="WinJS.UI.ListView"></div>

var object = new WinJS.UI.ListView(parentObject, options);

Members

The ListView object has these types of members:

Constructors
Events
Methods
Properties

Constructors

The ListView object has these constructors.

Constructor	Description
ListView	Creates a new ListView.

Events

The ListView object has these events.

Event	Description
oncontentanimating	Raised when the ListView is about to play an entrance or contentTransition animation.
onfootervisibilitychanged	Raised when the footer's visibility property changes.
ongroupheaderinvoked	Raised when the user taps or clicks a group header.
onheadervisibilitychanged	Raised when the header's visibility property changes.
onitemdragbetween	Raised when the ListView is a drop target and the onitemdragenter has been disabled. This is raised every time the cursor is moved between a new pair of items. If you call preventDefault on this event, then the ListView doesn't move the items slightly above/below the cursor to provide visual feedback for a drop.
onitemdragchanged	Raised when the user is dragging an item from the ListView and the itemDataSource changes while the user is dragging.
onitemdragdrop	Raised when an item is dropped onto the ListView as the result of a drag operation.
onitemdragend	Raised when the user drops an item dragged from a ListView.
onitemdragenter	Raised when an dragged item enters the bounds of the ListView control.
onitemdragleave	Raised when a draggable item leaves the bounds of a ListView control.
onitemdragstart	Raised when the user begins to drag an item from a ListView control.
oniteminvoked	Raised when the user taps or clicks an item.
onkeyboardnavigating	Raised when the focused item changes.
onloadingstatechanged	Raised when the ListView control's loadingState changes.
onselectionchanged	Raised after the current selection changes.
onselectionchanging	Raised just before the current selection changes.

Methods

The ListView object has these methods.

Method	Description
addEventListener	Registers an event handler for the specified event.
dispatchEvent	Raises an event of the specified type and with additional properties.
dispose	Releases resources held by this object. Call this method when the object is no longer needed. After calling this method, the object becomes unusable.
elementFromIndex	Returns the DOM element that represents the item at the specified index.
ensureVisible	Makes the item at the specified index visible. If necessary, the ListView will scroll to the item.
forceLayout	Forces the ListView to update its layout. Use this method when you make the ListView visible again after its style.display property had been set to "none".
indexOfElement	Returns the index of the item that the specified DOM element displays.
loadMorePages	Loads the next set of pages if the ListView control's loadingBehavior is set to "incremental" (otherwise, it does nothing). The number of pages to be loaded is determined by the pagesToLoad property.
recalculateItemPosition	Repositions all the visible items in the ListView to adjust for items whose sizes have changed. Most apps won'’t ever need to call this method. For more info, see the Remarks section.
removeEventListener	Removes an event handler that the addEventListener method registered.
triggerDispose	Triggers the ListView disposal service manually.

Properties

The ListView object has these properties.

Property	Access type	Description
automaticallyLoadPages	Read/write	Gets or sets a value that indicates whether the next set of pages is automatically loaded when the user scrolls beyond the number of pages specified by the pagesToLoadThreshold property.
currentItem	Read/write	Gets or sets an object that indicates which item should have keyboard focus and the focus state of that item.
element	Read-only	Gets the DOM element that hosts this ListView.
footer	Read/write	Gets or sets the HTML element that contains the footer.
groupDataSource	Read/write	Gets or sets the data source that contains the groups for the items in the itemDataSource.
groupHeaderTapBehavior	Read/write	Gets or sets how the ListView reacts when the user taps or clicks a group header.
groupHeaderTemplate	Read/write	Gets or sets the Template or function that creates the DOM elements for each group header in the groupDataSource. Each group header can contain multiple elements, but it must have a single root element.
header	Read/write	Gets or sets the HTML element that contains the header.
indexOfFirstVisible	Read/write	Gets or sets the first visible item.
indexOfLastVisible	Read-only	Gets the index of the last visible item in the ListView.
itemDataSource	Read/write	Gets or sets the data source that provides the ListView with items.
itemsDraggable	Read/write	Gets or sets a value that specifies whether items can be dragged. When this is set to true, the ListView provides built in behaviors related to item dragging.
itemsReorderable	Read/write	Gets or sets a value that specifies whether the ListView control's items can be reordered within itself by dragging and dropping.
itemTemplate	Read/write	Gets or sets the WinJS.Binding.Template or templating function that creates the DOM elements for each item in the itemDataSource. Each item can contain multiple elements, but it must have a single root element.
layout	Read/write	Gets or sets an object that controls the layout of the ListView.
loadingBehavior	Read/write	Gets or sets a value that specifies how the ListView fetches items and adds and removes them to the DOM. Don't change the value of this property after the ListView has begun loading data.
loadingState	Read-only	Gets a value that indicates whether the ListView is still loading or whether loading is complete.
maxDeferredItemCleanup	Read/write	Gets or sets the maximum number of realized items.
maxLeadingPages	Read/write	Gets or sets the maximum number of pages to prefetch for the leading buffer.
maxTrailingPages	Read/write	Gets or sets the maximum number of pages to prefetch for the trailing buffer.
pagesToLoad	Read/write	Gets or sets the number of pages to load when the loadingBehavior property is set to "incremental" and the user scrolls beyond the threshold specified by the pagesToLoadThreshold property.
pagesToLoadThreshold	Read/write	Gets or sets the threshold (in pages) for initiating an incremental load. When the last visible item is within the specified number of pages from the end of the loaded portion of the list, and if automaticallyLoadPages is true and loadingBehavior is set to "incremental", the ListView initiates an incremental load.
resetGroupHeader	Read/write	Gets or sets the function that is called when the ListView discards or recycles the element representation of a group header.
resetItem	Read/write	Gets or sets the function that is called when an item is removed, an item is changed, or an item falls outside of the realized range of the ListView.
scrollPosition	Read/write	Gets or sets the distance, in pixels, of the start of the viewable area within the viewport.
selection	Read-only	Gets an ISelection that contains the range of currently selected items.
selectionMode	Read/write	Gets or sets a value that specifies how many ListView items can be selected.
swipeBehavior	Read/write	Gets or sets how the ListView reacts to the swipe gesture. The swipe gesture can select the swiped items or can have no effect on the current selection.
tapBehavior	Read/write	Gets or sets how the ListView reacts when the user taps or clicks an item.
zoomableView	Read-only	Gets a ZoomableView that supports semantic zoom functionality. This API supports the semantic zoom infrastructure and is not intended to be used directly from your code.

Remarks

The ListView can accept data from several different types of sources, such as Really Simple Syndication (RSS) feeds or lists of images. To learn how to create your first ListView, see the Add a ListView Quickstart.

Items in a ListView control can contain other controls, but they can't contain a FlipView or another ListView.

Asynchronous function issue

ListView can be used in an asynchronous environment except when using embedded components that only support synchronous functionality (such as Repeater).

Styling the ListView

CSS classes

To customize the ListView, you can define your own styles for these Cascading Style Sheets (CSS) classes (defined by the Windows Library for JavaScript style sheets):

Note

Windows 8.1 In previous versions of Windows, ListView items can be styled using the CSS selector .win-container .win-item. Starting with Windows 8.1, another element contains items within the ListView, and so CSS selectors to style items need to be written as .win-container .win-itembox .win-item.
Windows 8.1 In Windows 8.1, the win-groupheader CSS class introduces noticeable margins in an app. Use win-groupleader instead.

CSS class	Description
win-container	Styles the container for an item in the ListView.
win-container-even	Styles the container for even item in the ListView.
win-container-odd	Styles the container for odd item in the ListView.
win-groupheader	Styles the group headers of a ListView that contains group information.
win-item	Styles items in the ListView.
win-listview	Styles the entire ListView.
win-progress	Styles the progress indicator of the ListView.
win-selectionbackground	Styles the background of an item's selection checkmark.
win-selectioncheckmark	Styles an item's selection checkmark.
win-surface	Styles the scrollable region of the ListView.
win-viewport	Styles the viewport of the ListView.

Note Some of these classes (such as win-item) are used by multiple WinJS controls. To apply a style to just the ListView, add .win-listview to the style selector. For more info, see Styling the ListView and its items.

Setting the ListView control's height

The ListView does not dynamically adjust its height to fit your content. For a ListView to render, you must specify an absolute value for its height. The WinJS style sheets set the ListView control's height to 400 pixels.

This example overrides the default style for ListView controls and sets their height to 500 pixels.

.win-listview 
{
    height: 500px; 
}

The win-listview class is a class defined by the WinJS that you can use to style the ListView. The example you just saw changes the height of every ListView to 500 pixels. To change just one ListView, add the ID of the ListView control's hosting div element to the selector. This example changes the height of the ListView with the ID "basicListView".

#basicListView.win-listview 
{
    height: 500px; 
}

Maximum number of items

The ListView doesn't support more than 1.5 million pixels worth of items.

Detaching the ListView from the DOM

Don't use a ListView control after you've detached it from the DOM. When you detach a ListView from the DOM, it starts releasing resources to free up memory and won't work properly anymore.

Using a ListView in a PageControl

When you use a ListView inside a PageControl, add this code to your PageControl object's ready method to ensure that the ListView gets the correct reading order:

element.setAttribute("dir", window.getComputedStyle(this._element, null).direction);

Examples

This example creates an item template and a ListView.

<div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template">
    <div style="width: 282px; height: 70px; padding: 5px; overflow: hidden; display: -ms-grid;">

        <!-- Displays the "picture" field. -->
        <img data-win-bind="alt: title; src: picture"
            src="#"
            style="width: 60px; height: 60px; margin: 5px; -ms-grid-column: 1;" />
        <div style="margin: 5px; -ms-grid-column: 2">

            <!-- 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'),
    layout : {type: WinJS.UI.GridLayout}}">
</div>

The next example defines the data for the ListView in a separate JavaScript file. For the ListView to access the data, add a reference to the JavaScript file to the HTML page that contains the ListView.

// data.js
(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 itemList = new WinJS.Binding.List(dataArray);

    // Create a namespace to make the data publicly
    // accessible. 
    var publicMembers =
        {
            itemList: itemList
        };
    WinJS.Namespace.define("DataExample", publicMembers);

})();

For a full walkthrough of the code and more info about creating your first ListView, see Quickstart: Add a ListView.

Requirements

Minimum WinJS version	WinJS 1.0
Namespace	WinJS.UI

Partager via