ListView

Using a ListView requires the ListView module.

import * as listViewModule from "tns-core-modules/ui/list-view";

Other modules which will be used in the code samples in this article:

import * as observableArray from "tns-core-modules/data/observable-array";
import * as labelModule from "tns-core-modules/ui/label";

Binding the ListView items property to collection in the view-model.

<Page>
  <ListView items="{{ myItems }}" />
</Page>

Attaching event handler for the ListView itemTap event.

<Page>
  <ListView items="{{ myItems }}" itemTap="listViewItemTap" />
</Page>
function listViewItemTap(args) {
    var itemIndex = args.index;
}
exports.listViewItemTap = listViewItemTap;

Attaching event handler for the ListView loadMoreItems event.

<Page>
 <ListView items="{{ myItems }}" loadMoreItems="listViewLoadMoreItems" />
</Page>
function listViewLoadMoreItems(args) {
    // Expand your collection bound to the ListView with more items here!
}

Define the ListView itemTemplate property.

<Page>
 <ListView items="{{ myItems }}">
    <ListView.itemTemplate>
       <Label text="{{ title || 'Downloading...' }}" textWrap="true" class="title" />
    </ListView.itemTemplate>
 </ListView>
</Page>

Define multiple item templates and an item template selector in XML.

The itemTemplateSelector can be an expression specified directly in XML. The context of the expression is the data item for each row.

<Page>
 <ListView items="{{ myItems }}" itemTemplateSelector="age > 18 ? 'green' : 'red'">
    <ListView.itemTemplates>
      <template key="green">
        <Label text="{{ age }}" style.backgroundColor="green" />
      </template>
      <template key="red">
        <Label text="{{ age }}" style.backgroundColor="red" />
      </template>
    </ListView.itemTemplates>
 </ListView>
</Page>

Specifying the item template selector as a function in the code-behind file

In case your item template selector involves complicated logic which cannot be expressed with an expression, you can create an item template selector function in the code behind of the page in which the ListView resides. The function receives the respective data item, the row index and the entire ListView items collection as parameters. It has to return the the key of the template to be used based on the supplied information.

<Page>
 <ListView items="{{ myItems }}" itemTemplateSelector="selectItemTemplate">
    <ListView.itemTemplates>
      <template key="green">
        <Label text="{{ age }}" style.backgroundColor="green" />
      </template>
      <template key="red">
        <Label text="{{ age }}" style.backgroundColor="red" />
      </template>
    </ListView.itemTemplates>
 </ListView>
</Page>
export function selectItemTemplate(item: Item, index: number, items: Array<Item>) {
    return item.age % 2 === 0 ? "red" : "green";
}

Alternating row colors

You can use the special value '$index' in the item template selector expression which represents the row index.

<Page>
 <ListView items="{{ myItems }}" itemTemplateSelector="$index % 2 === 0 ? 'even' : 'odd'">
    <ListView.itemTemplates>
      <template key="even">
        <Label text="{{ age }}" style.backgroundColor="white" />
      </template>
      <template key="odd">
        <Label text="{{ age }}" style.backgroundColor="gray" />
      </template>
    </ListView.itemTemplates>
 </ListView>
</Page>

Creating a ListView

var listView = new listViewModule.ListView();

Using ListView with Array

The itemLoading event is used to create the UI for each item that is shown in the ListView.

var colors = ["red", "green", "blue"];
listView.items = colors;
listView.on(listViewModule.ListView.itemLoadingEvent, function (args: listViewModule.ItemEventData) {
    if (!args.view) {
        // Create label if it is not already created.
        args.view = new labelModule.Label();
    }
    (<labelModule.Label>args.view).text = colors[args.index];

});

Note, that changing the array after the list view is shown will not update the UI. You can force-update the UI using the refresh() method.

colors.push("yellow");
// Manually trigger the update so that the new color is shown.
listView.refresh();

Using ListView with ObservableArray

var colors = new observableArray.ObservableArray(["red", "green", "blue"]);
listView.items = colors;
listView.on(listViewModule.ListView.itemLoadingEvent, function (args: listViewModule.ItemEventData) {
    if (!args.view) {
        // Create label if it is not already created.
        args.view = new labelModule.Label();
    }
    (<labelModule.Label>args.view).text = colors.getItem(args.index);

    indexes[args.index] = true;
});

When using ObservableArray the list view will be automatically updated when items are added or removed form the array.

colors.push("yellow");
// The ListView will be updated automatically.

Responding to other events

ItemTap event

The event will be raise when an item inside the ListView is tapped.

listView.on(listViewModule.ListView.itemTapEvent, function (args: listViewModule.ItemEventData) {
    var tappedItemIndex = args.index;
    var tappedItemView = args.view;
    // Do someting
});

LoadMoreItems event

The event will be raised when the ListView is scrolled so that the last item is visible. This even is intended to be used to add additional data in the ListView.

listView.on(listViewModule.ListView.loadMoreItemsEvent, function (data: observable.EventData) {
    // Do something.
});
// ```

Stay connected with NativeScript

(expect a newsletter every 4-8 weeks)

NativeScript
NativeScript is licensed under the Apache 2.0 license .
© Progress Software Corporation. All Rights Reserved.