Windows Dev Center

WinJS.UI.ListView object

[This documentation is preliminary and is subject to change.]

Applies to: Metro style apps only

Displays data items in a customizable list or grid.

Syntax


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


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

Members

The ListView object has these types of members:

Events

The ListView object has these events.

EventDescription
iteminvoked

Occurs when the user taps or clicks an item.

loadingstatechanged

Occurs when the ListView switches between a loading and a ready state.

selectionchanged

Occurs after the current selection changes.

selectionchanging

Occurs just before the current selection changes.

 

Methods

The ListView object has these methods.

MethodDescription
addEventListener

Registers an event handler for the specified event.

dataObject

This method supports the Windows Library for JavaScript infrastructure and is not intended to be used directly from your code.

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 function when making 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.

ListView

Creates a new ListView.

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.

refresh

Forces the ListView to regenerate its DOM representation of its list items.

removeEventListener

Removes an event handler that the addEventListener method registered.

scrollTo

Scrolls the ListView so that the specified item is displayed first.

 

Properties

The ListView object has these properties.

PropertyDescription

automaticallyLoadPages

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

Gets or sets the ListView item that has focus.

element

Gets the HTML element that hosts this ListView.

groupDataSource

Gets or sets the data source that contains the groups for the items in the itemDataSource.

groupHeaderTemplate

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.

indexOfFirstVisible

Gets or sets the first visible item.

indexOfLastVisible

Gets the index of the last visible item in the ListView.

itemDataSource

Gets or sets the data source that provides the ListView with items.

itemTemplate

Gets or sets the Template or 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

Gets or sets an object that controls the layout of the ListView.

loadingBehavior

Gets or sets a value that specifies how many items are loaded into the DOM.

loadingState

Gets a value that indicates whether the ListView is still loading or whether loading is complete.

pagesToLoad

Gets or sets the number of pages to load when the user scrolls beyond the threshold the pagesToLoadThreshold property specifies if the loadingBehavior property is set to "incremental".

pagesToLoadThreshold

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

Gets or sets the function that is called when the ListView recycles the element representation of a group header.

resetItem

Gets or sets the function that is called when the ListView recycles the element representation of an item.

scrollPosition

Gets or sets the distance, in pixels, between the first item in the list and the current viewable area.

selection

Gets the ListView object's currently selected items.

selectionMode

Gets or sets the selection mode of the ListView.

swipeBehavior

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

Gets or sets how the ListView reacts when the user taps or clicks an item.

zoomableView

Gets a ZoomableView that supports semantic zoom functionality. This API supports the SemanticZoom 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 RSS feeds or lists of images. To learn how to create your first ListView, see the Add a ListView Quickstart.

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):

CSS classDescription

win-container

Styles the container for an 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 that some of these classes (such as win-item) are used by multiple Windows Library for JavaScript controls. To apply a style to just the ListView, add .win-listview to the style selector.

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 Windows Library for JavaScript 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 Windows Library for JavaScript 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; 
}

Setting margins around the ListView

The ListView supports margins on its left, top, and bottom sides, but you can't specify a margin for its right side. One workaround is to add an element that's as wide as the margin you want and set its style.visiblity property to "none", then add the element to the right of the ListView.

Examples

This example creates an item template and a ListView.


    <div id="mediumListIconTextTemplate" data-win-control="WinJS.Binding.Template">
        <div>

            <!-- Displays the "picture" field. -->
            <img 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: description"></h6>
            </div>
        </div>
    </div>     

    <div id="basicListView" data-win-control="WinJS.UI.ListView" 
        data-win-options="{itemDataSource : DataExample.itemList.dataSource, itemTemplate: mediumListIconTextTemplate}">
    </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.


(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); 

})();

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

Requirements

Minimum supported client

Windows 8 Consumer Preview

Minimum supported server

Windows Server 8 Beta

Namespace

WinJS.UI

Library

Ui.js

See also

Quickstart: Add a ListView
Getting started with ListView sample
ListView item templates sample
ListView grouping and SemanticZoom sample

 

 

Build date: 2/10/2012

Ajouts de la communauté

AJOUTER
Afficher:
© 2015 Microsoft