快速入門：新增 ListView (HTML)

  • 發行項

[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App，請參閱 最新文件 ]

大部分應用程式都會顯示資料的清單，例如，連絡人清單、圖庫中的影像，或是電子郵件收件匣的內容。這些清單可以從資料庫、網路或 JSON 資料來源取得資料。 WinJS 提供 ListView 控制項，您可以使用這個控制項顯示資料。

先決條件

您必須能夠使用 JavaScript，以 WinJS 控制項建立基本的 Windows 執行階段應用程式。如需開始使用 WinJS 控制項的指示，請參閱快速入門：新增 WinJS 控制項與樣式。

什麼是 ListView？

ListView 是 WinJS 控制項，這個控制項會顯示可自訂清單或格線中的 IListDataSource 資料。 WinJS 提供數種 IListDataSource 物件類型：

您也可以建立自訂的資料來源，讓它連接到其他類型的資料提供者，例如 Web 服務或資料庫。如需指示，請參閱如何建立自訂資料來源。

建立 ListView

Hh465496.wedge(zh-tw,WIN.10).gif建立 ListView

  1. 將 WinJS 的參考新增到您的 HTML 檔案 (如果尚未新增)。

    使用最新版的 WinJS：

    1. 從取得 WinJS 下載最新版，並複製到您應用程式或網站的目錄中。
    2. 將 WinJS CSS 與指令碼參考新增到您使用 WinJS 功能之應用程式或網站的各個頁面。
    
<!-- WinJS references -->
<link href="/WinJS/css/ui-dark.css" rel="stylesheet">
<script src="/WinJS/js/WinJS.js"></script>

    這個範例顯示當您在 Microsoft Visual Studio 建立新的 [空白應用程式] 專案時，所產生之 default.html 檔案的 HTML。

    
<!-- 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>

  2. 在 HTML 檔案中，建立 div 元素，並將其 data-win-control 屬性設定為 WinJS.UI.ListView。

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

  3. 在隨 HTML 檔案提供的 JavaScript 程式碼中，當載入 HTML 時呼叫 WinJS.UI.processAll 函式。

    WinJS.UI.processAll();

    下一個範例顯示當您建立新的 [空白的應用程式] 專案時，與 default.html 檔案一起建立的 default.js 檔案。

    
(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，您將不需要呼叫 WinJS.UI.processAll，因為頁面控制項會為您進行這個動作。如果您要將 ListView 新增到自訂的 HTML，可以使用 DOMContentLoaded 事件呼叫 WinJS.UI.processAll。如需啟用控制項的詳細資訊，請參閱快速入門：新增 WinJS 控制項與樣式。

此程式碼會建立空白的 ListView。如果您執行應用程式，還看不到任何東西。在下一節中，您要建立一些資料供 ListView 顯示。

定義資料

輸入程式碼，將資料來源建立在不同的 JavaScript 檔案中，可方便進行維護。在本節中，您會了解如何建立資料的 JavaScript 檔案、如何建立 List，以及如何使用 WinJS.Namespace.define 函式讓整個應用程式存取資料。

  1. 使用 Visual Studio，將資料檔案新增到專案。在 [方案總管] 中，用滑鼠右鍵按一下專案的 js 資料夾，然後選取 [加入] > [新增項目]****。隨即顯示 [加入新項目] 對話方塊。

  2. 選取 [JavaScript 檔]****。將它命名為 "dataExample.js"。 按一下 [加入] 建立檔案。Visual Studio 會建立名為 dataExample.js 的空白 JavaScript 檔案。

  3. 開啟 dataExample.js。建立匿名函式，然後開啟 strict 模式。

    如撰寫基本 app 的程式碼中所述，最好是將 JavaScript 程式碼包在匿名函式中進行封裝，並使用 strict 模式。

    (function () {
    "use strict"; 





})();

  4. 建立資料陣列。這個範例會建立物件的陣列。每個物件都有三個屬性：title、text 和 image。

    (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 範例取得圖片 (這不是同一個範例，但使用相同的影像)。不新增影像，範例仍然可以執行。

     

  5. 使用陣列建立 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); 

})();

  6. 藉由宣告命名空間以及將 List 新增為 Public 成員的方式，公開 List。

    由於您剛才撰寫的程式碼是包含在匿名函式中，因此全都無法公開存取。這也是使用匿名函式的部分原因：讓私有資料維持私有。若要讓您的 ListView 能夠存取 List，必須讓它能夠公開存取。其中一種方法是使用 WinJS.Namespace.define 函式建立命名空間，並新增 List 做為其中一個成員。

    WinJS.Namespace.define 函式使用兩個參數：要建立的命名空間名稱，以及包含一或多個屬性/值組的物件。每個屬性都是成員的公用名稱，而每個值是您私用程式碼中想要公開的基本變數、屬性及函式。

    這個範例會建立名為 DataExample 的命名空間，該命名空間會公開名為 itemList 的 Public 成員，而這個成員會傳回您的 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

  1. 在包含 ListView 的 HTML 檔案 head 區段中，將參考新增到剛才建立的資料檔案 (dataExample.js) 中：

    <head>
    <!-- Other file references ... -->

    <!-- Your data file. -->
    <script src="/js/dataExample.js"></script>

</head>

  2. 使用上一節建立的資料來設定 ListView 控制項的 itemDataSource 屬性。

    itemDataSource 屬性接受 IListDataSource 物件。List 物件不是 IListDataSource，但卻有可以傳回自己的 IListDataSource 版本的 dataSource 屬性。

    若要連接資料，請將 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 很容易建立：定義想要用以顯示每個清單項目的標記，然後指出要顯示每個資料欄位的位置。

  1. 在 HTML 中，建立 WinJS.Binding.Template 控制項，然後指派識別碼。此範例使用識別碼 "mediumListIconTextTemplate"。

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

    </div>

    注意  您的範本必須先定義才能使用，因此，請在 ListView 的 HTML 前面新增我們的範本 HTML。

     

  2. WinJS.Binding.Template 必須有單一根元素。建立 div 元素做為範本內容的父系。

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

        </div>
    </div>

  3. 建立 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>

  4. 為了避免配置問題，請務必指定範本根元素的大小，並務必指定範本中 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>

  5. 在每個顯示資料的元素上設定 data-win-bind 屬性。data-win-bind 屬性使用下列語法：

    data-win-bind="propertyName: dataFieldName"

     

    例如，若要將 img 的 src 屬性繫結至 "picture" 欄位，請使用下列語法：

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

  6. 若要使用項目範本，請使用 select 語法將 ListView 的 itemTemplate 屬性設到您的項目範本。

        <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 不會動態調整其高度以符合您的內容。若要呈現 ListView，您必須指定其高度的絕對值。WinJS 樣式表會將 ListView 控制項高度設成 400px，但使用自己的 CSS 覆寫預設樣式來指定自己的高度，會更加容易。將此 CSS 新增到您應用程式的 CSS 檔案，以設定 ListView 的高度和寬度，並提供框線：

適用於 Windows 的 ListView 樣式

.win-listview 
{
    height: 500px; 
    width: 500px; 
    border: 2px solid gray;
}

適用於 Windows Phone 8.1 的 ListView 樣式

.win-listview 
{
    height: 400px; 
    width: 300px; 
    border: 2px solid gray;
}

win-listview 是由 WinJS 所定義的類別，您可以使用這個類別設定 ListView 的樣式。您剛才看到的範例會變更每一個 ListView 的高度、寬度與框線。若只要變更一個 ListView，請將 ListView 控制項之主控 div 元素的識別碼新增到選取器：

適用於 Windows 的特定 ListView 樣式

#basicListView .win-listview 
{
    height: 500px; 
    width: 500px; 
    border: 2px solid gray;
}

適用於 Windows Phone 8.1 的特定 ListView 樣式

#basicListView .win-listview 
{
    height: 400px; 
    width: 300px; 
    border: 2px solid gray;
}

執行應用程式。現在，ListView 夠大，可以顯示所有項目。

500px ListView 控制項。

WinJS 樣式表會定義 CSS 類別，您可以覆寫這些類別以自訂 WinJS 控制項的外觀及操作方式。與 ListView 搭配使用的 CSS 類別包括：

  • win-listview

    指定 ListView 本身的樣式。

  • win-container

    指定 ListView 或 FlipView 項目容器的樣式。每個項目都有自己的容器。

  • win-progress

    指定進度控制項的樣式，這個控制項會在 ListView 載入項目時顯示。

如需完整的清單，請參閱 ListView reference page。

這個範例定義的樣式會在 ListView 中的每個項目容器周圍新增邊界。


#basicListView .win-listview .win-container {
    margin: 10px; 
}

ListView 中已設定樣式的項目

下一個範例定義的樣式會在暫留狀態下套用至 ListView 中的清單項目。

#basicListView .win-listview .win-container:hover {
    color: red;
}

注意  

ListView 支援左側、上方以及下方的邊界，但您無法指定右側的邊界。解決方法是新增一個與您所需邊界同寬的元素，並將其 style.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 現在看起來的樣子：

含有已設定樣式之項目的 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) 若要使用儲存格配置，請將 layout 屬性設為 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

若要了解其方式，請參閱如何在 ListView 中群組項目。

將互動式元素新增至項目範本

注意  項目範本可包含大部分其他控制項，但不可包含 FlipView 或另一個 ListView。

 

選取和叫用 ListView 項目

通常使用者在與元素互動時，ListView 會擷取該互動，並用它來判斷使用者是否已選取或叫用項目，或是在項目間移動瀏覽。您必須將 win-interactive CSS 類別附加到互動式元素或其父元素之一，才能讓控制項這類互動式元素接收輸入。該元素與其子項接收互動，而且不再觸發 ListView 的事件。

當您將 win-interactive 附加到項目範本中的元素時，請勿讓元素填滿整個項目，否則使用者將無法選取或啟動該項目。

若要新增互動式元素至項目範本，建議您使用範本函式，而不是 WinJS.Binding.Template。 如需範本函式的詳細資訊，請參閱如何建立範本函式。

在 ListView 新增重新排序和拖放功能 (僅限 Windows)

ListView 控制項也允許使用者重新排序和拖放個別項目。例如，您可以將 ListView 的 itemsDraggable 屬性設為 'true'，藉以宣告拖曳功能。同樣地，若要允許使用者重新排序 ListView 控制項中的項目，您可以將 ListView 的 itemsReorderable 屬性設為 '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 中群組項目。