共用方式為

快速入門：使用單頁瀏覽 (HTML)

  • 發行項

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

了解單頁瀏覽模型，以及如何使用 PageControl 物件和 WinJS.Navigation 功能，在自己的應用程式中實作這種模型。

為協助您的應用程式選擇最佳的瀏覽模式，請參閱瀏覽模式。

另外也可以參閱應用程式功能，從開始到完成系列中的單層瀏覽和階層式瀏覽模式。

先決條件

建立基本連結

最簡單且最常見的瀏覽形式之一就是超連結。下列 HTML 程式碼會建立瀏覽到 page2.html 的超連結。

<p><a href="page2.html">Go to page 2</a></p>

因為它是一個相對連結，所以系統會假設 page2.html 是屬於應用程式一部分的本機頁面，與目前文件的基礎 URL 相關。 例如，如果連結出現在 /folder/default.html 中，按一下該連結就會前往 /folder/page2.html。

注意  如果您已將應用程式最佳化以進行當地語系化 (這一向是個好主意)，這個行為會根據您在 /folder/ 底下已當地語系化的內容資料夾而有所不同。請參閱全球化應用程式。

 

如果您想要明確指定完整 URI 以取得應用程式中的本機檔案，請使用新的 packaged-content URL 配置 (ms-appx)，如下：

  • **ms-appx://package name/**file path

您可以視需要省略套件名稱。

  • **ms-appx:///**file path

這裡提供一個範例。

<p><a href="ms-appx:///page2.html">Go to page 2</a></p>

您可以使用 ms-appx URL 配置指定應用程式套件中所包含的任何檔案。但是，建議使用相對 URL，因為相對 URL 會根據文件的基礎 URL 自動解析。

單頁瀏覽：建議的模型

上一個範例說明如何建立可執行最上層瀏覽的連結。這不會對網頁造成問題，但基於以下幾個原因，您不應該在應用程式中執行最上層瀏覽：

  • 應用程式載入下一個頁面時畫面會變成空白。
  • 指令碼內容會被摧毀且必須再次初始化。應用程式可能會接收系統事件，但不會進行處理，因為指令碼內容已被摧毀且重新初始化。

相較於最上層瀏覽，使用單頁瀏覽不但可提供更好的效能，也可提供與應用程式更類似的使用者經驗。新的 Microsoft Visual Studio 專案不會自動提供導覽控制項，因此新頁面的最上層瀏覽代表無法回到第一頁，除非您手動建立連結或其他瀏覽機制才能返回。此外，您的起始頁是定義應用程式如何管理生命週期的位置—在應用程式啟動、關閉或暫停等情況下的行為。如果您的最上層有多個頁面，則每個頁面都必須包含管理應用程式生命週期及狀態的邏輯。

您應該使用哪個控制項將內容載入主頁面？

  • 您可以使用文件物件模型 (DOM) 從另一個來源載入文件。
  • 對於簡單的 HTML 內容 (也就是不能互動且不包含指令碼參考的內容)，請使用 HtmlControl 物件。
  • 針對外部 Web 內容，請在適當時使用 x-ms-webview 控制項。相較於 iframe，這個控制項提供更好的隔離、瀏覽、SmartScreen 篩選工具可用性，以及支援無法在 iframe 中裝載的網站。
  • 對於所有其他的內容，請使用頁面控制項。

Visual Studio 提供數個適用於應用程式的 JavaScript 專案範本，讓瀏覽管理變得更容易。這些專案範本提供一個名為 PageControlNavigator 的導覽控制，可用來在 PageControl 物件間進行瀏覽。 PageControlNavigator 類別示範一個可以使用 PageControl 來執行單頁瀏覽的方式。

後續步驟說明如何建立包含多個 PageControl 物件的應用程式，以及如何使用單頁瀏覽模型在這些頁面之間瀏覽。

步驟 1：建立新的 [瀏覽應用程式] 專案

  1. 啟動 Microsoft Visual Studio 2013 Update 2。

    注意  第一次執行 Visual Studio 時，會提示您取得開發人員授權。

     

  2. 選擇 [檔案] > [新增專案]，或從 [起始頁] 索引標籤中按一下 [新增專案]。隨即開啟 [新增專案] 對話方塊。

  3. 在左側的 [範本]**** 窗格中，展開 [已安裝的] => [範本]**** => [JavaScript] => [市集應用程式]****。

  4. 選取 [通用應用程式] 範本類型。適用於 JavaScript 的可用專案範本會顯示在對話方塊的中央窗格中。

  5. 在中央窗格中，選取 [瀏覽應用程式 (通用應用程式)]**** 專案範本。

  6. 在 [名稱] 文字方塊中，輸入專案的名稱。這個主題中的範例使用 "NavigationAppExample"。

    [新增專案] 對話方塊顯示 JavaScript 通用應用程式範本。

  7. 按一下 [確定]**** 來建立專案。

    新的 [瀏覽應用程式] 專案包含一個起始頁、一個首頁以及一些其他的支援檔案。它在 [方案總管]**** 中看起來像這樣。

    新 [瀏覽應用程式] 專案中的檔案。

    新的 [瀏覽應用程式] 專案包含多個檔案。有些是 Windows 應用程式專用檔案，有些是 Phone 應用程式專用檔案，有些則是共用檔案。

    專案包含下列 HTML 檔案：

    • default.html—起始頁。它是最先載入的。它包含 PageControlNavigator 的執行個體 (它會將每個頁面載入主視窗)，它也是建立 AppBar 的位置 (如果您的應用程式需要使用的話)。注意  HTML 頁面會載入到單一內容容器，這是在 default.html 中宣告的 div 元素。在 default.html 中，會使用適用於 JavaScript 的 Windows Library (WinJS) 所提供的 data-win-control 屬性，將內容容器 div 元素宣告為 PageControlNavigator 類型的控制項。  
    • home.html—首頁。它會顯示「歡迎」標題。

    專案包含下列 JavaScript 檔案：

    • default.js—會指定應用程式啟動時的行為。
    • home.js—會指定與首頁關聯的行為。
    • navigator.js—會實作 PageControlNavigator 物件，它支援 Windows 市集應用程式 JavaScript 範本的瀏覽模型。

    專案包含下列 CSS 檔案：

    • default.css—會指定內容容器頁面及應用程式整體的階層式樣式表 (CSS) 樣式。
    • home.css—會指定首頁的 CSS 樣式。

    專案也包含 package.appxmanifest 檔案，用來描述應用程式套件。最後，這個專案也包含數個影像檔，像是啟動顯示畫面影像的 splashscreen.png 以及用於 Windows 市集的 storelogo.png。

  8. 執行應用程式。選擇 [偵錯] > [開始偵錯]****，或者選擇 F5 (選擇 SHIFT + F5，可停止偵錯並返回 Visual Studio)。

    以下為 Windows 應用程式的螢幕擷取畫面。

    這是新的 Windows 瀏覽應用程式。

    以下為 Phone 應用程式的螢幕擷取畫面。

    這是新的 Phone 瀏覽應用程式。

    請注意，您看到的內容不是定義在 default.html 檔案中。它是定義在 home.html 檔案中 (另一個頁面)。PageControlNavigator 會擷取首頁內容並在 default.html 中顯示這些內容。

    這裡顯示瀏覽控制項 PageControlNavigator。它定義用來瀏覽的數個函式。這個控制項是實作於 navigator.js。

    
WinJS.Namespace.define("Application", {
    PageControlNavigator: WinJS.Class.define(
        // Define the constructor function for the PageControlNavigator.
        function PageControlNavigator(element, options) {
            // Initialization code.
            }, {
                // Members specified here.
            }
    ), // . . .
});

    建構函式會執行瀏覽控制項的初始化。幾個重要的初始化工作包含設定 WinJS 事件 (如 WinJS.Navigation.onnavigating 事件) 的處理常式，以及設定應用程式的首頁 (首頁值是指定於 data-win-options 屬性的 contenthost DIV 元素中)。

    
// Initialization code.
this.home = options.home;
// . . .
// The 'nav' variable is set to WinJS.Navigation.
addRemovableEventListener(nav, 'navigating', this._navigating.bind(this), false);
addRemovableEventListener(nav, 'navigated', this._navigated.bind(this), false);

    宣告為應用程式瀏覽控制項 (在 default.html 中) 的 DIV 元素，會為應用程式的所有頁面提供內容容器。DIV 元素使用 WinJS data-win-control 屬性，將自己宣告為瀏覽控制項，而此控制項會為應用程式提供瀏覽模型。所有頁面內容都會載入到這個 DIV。

    這裡是 default.html 頁面的完整標記。

    
<!-- default.html -->
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>NavigationAppExample</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <!-- NavigationAppExample references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>
    <script src="/js/navigator.js"></script>
</head>
<body>
    <div id="contenthost" 
        data-win-control="Application.PageControlNavigator" 
        data-win-options="{home: '/pages/home/home.html'}"></div>
    <!-- <div id="appbar" data-win-control="WinJS.UI.AppBar">
        <button data-win-control="WinJS.UI.AppBarCommand" 
            data-win-options="{id:'cmd', label:'Command', icon:'placeholder'}">
        </button>
    </div> -->
</body>
</html>

    下圖顯示應用程式視窗中顯示的不同內容單元：

    瀏覽應用程式的內容解析。

在後續步驟中，您將深入了解如何使用 PageControlNavigator 和 PageControl 物件新增頁面。

步驟 2：建立新頁面

PageControl 是做為邏輯網頁之 HTML、CSS 以及 JavaScript 的模組單位。

將新頁面新增到 Visual Studio 2013 專案時，您需要：

  1. 使用 Visual Studio 中的頁面控制項範本來新增頁面。
  2. 使用 WinJS.Navigation.navigate 函式新增瀏覽到新頁面的程式碼。秘訣  這個函式不會直接執行瀏覽，但是會叫用 WinJS.Navigation.onnavigated 事件，而這個事件會在 navigator.js 中處理。navigator.js 中的程式碼會呼叫新頁面中的 ready 函式。通常您並不需要修改 navigator.js。  
  3. 必要時，新增適用於應用程式的 UI 和事件處理常式，以叫用頁面瀏覽程式碼。

頁面有一組程式庫可依照預先定義順序自動呼叫的預先定義方法。WinJS.UI.Pages.define 函式會公開這些方法以進行實作。

Hh452768.wedge(zh-tw,WIN.10).gif新增頁面

  1. 在 [方案總管] 中，使用滑鼠右鍵按一下 pages 資料夾，並依序選擇 [加入]**** > [新增資料夾]。注意  在這個範例中，我們新增共用頁面。您可以視需要在 Windows 或 Phone 專案新增專用的頁面。

     

  2. 將新資料夾命名為 page2。

  3. 在 page2 資料夾上按一下滑鼠右鍵，然後選取 [加入] > [新增項目]****。

  4. 在 [加入新項目] 對話方塊中，選擇中間窗格中的 [頁面控制項]****。

  5. 將頁面命名為 page2.html，然後選擇 [加入]。

    隨即會在 page2 資料夾中建立 page2.html 檔案，以及兩個其他的專案檔案：page2.css 和 page2.js。這三個檔案在一起代表一個邏輯頁面。

    秘訣  如果您將項目範本新增到專案中的其他地方，必須更新 page2.html 中的指令碼和 CSS 參考。

     

  6. 開啟 page2.js 並確認 define 函式中的 URI 正確。結果看起來應該像這樣。

    WinJS.UI.Pages.define("/pages/page2/page2.html", {
    // . . .
    ready: function (element, options) {
        // ready function implementation.
    },
    // . . .
});

步驟 3：自訂您的頁面

現在，修改新的頁面，讓它顯示不同的訊息以及一週天次。

  1. 開啟 page2.html。「頁面控制項」項目範本會建立一個 HTML 頁面，其中包含標頭區段 (區段中包含了 [返回] 按鈕) 以及放置頁面主要內容的區段。

    <!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>page2</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <link href="page2.css" rel="stylesheet" />
    <script src="page2.js"></script>
</head>
<body>
    <div class="page2 fragment">
        <header aria-label="Header content" role="banner">
            <button data-win-control="WinJS.UI.BackButton"></button>
            <h1 class="titlearea win-type-ellipsis">
                <span class="pagetitle">Welcome to page2</span>
            </h1>
        </header>
        <section aria-label="Main content" role="main">
            <p>Content goes here.</p>
        </section>
    </div>
</body>
</html>

  2. 用下面程式碼取代主要內容區段。

    
        <section aria-label="Main content" role="main">
            <p>Page controls make it easy to divide your app 
                into modular portions.</p>
            <p>Today is <span id="dayPlaceholder"></span>.</p>
        </section>

    您的 page2.html 檔案現在應該看起來像這樣。

    
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>page2</title>

    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <link href="page2.css" rel="stylesheet" />
    <script src="page2.js"></script>
</head>
<body>
    <div class="page2 fragment">
        <header aria-label="Header content" role="banner">
            <button data-win-control="WinJS.UI.BackButton"></button>
            <h1 class="titlearea win-type-ellipsis">
                <span class="pagetitle">Welcome to page2</span>
            </h1>
        </header>
        <section aria-label="Main content" role="main">
            <p>Page controls make it easy to divide your app 
                into modular portions.</p>
            <p>Today is <span id="dayPlaceholder"></span>.</p>
        </section>
    </div>
</body>
</html>

  3. 開啟 page2.js。PageControl 包含一組預先定義的函式，系統會按照預先定義的順序自動呼叫它們。「頁面控制項」項目範本包含 ready 函式以及 updateLayout 和 unload 函式。

    當使用者在直向和橫向之間切換或變更應用程式視窗大小時，PageControlNavigator 會呼叫 updateLayout 函式。 這個主題不會說明如何定義 updateLayout，但是每個 app 都必須定義它。請參閱將視窗大小調整為高窄格式配置的指導方針與通用 Windows 平台 (UWP) app 回應式設計入門。

    在載入頁面的 DOM、啟用控制項且將頁面載入主 DOM 時，會呼叫 ready 函式。

    (PageControl 支援其他適用於頁面生命週期的函式。如需詳細資訊，請參閱新增頁面控制項。)

    這裡是「頁面控制項」項目範本建立的 page2.js 檔案。

    
// page2.js
(function () {
    "use strict";

    WinJS.UI.Pages.define("/pages/page2/page2.html", {
        // This function is called whenever a user navigates to this page. It
        // populates the page elements with the app's data.
        ready: function (element, options) {
            // TODO: Initialize the page here.
        },

        unload: function () {
            // TODO: Respond to navigations away from this page.
        },

        updateLayout: function (element) {
            /// <param name="element" domElement="true" />

            // TODO: Respond to changes in layout.
        }
    });
})();

  4. 修改 ready 函式，讓它抓取您在步驟 2 中建立的範圍 ("dayPlaceholder")，然後將它的 innerText 設定為當天。

    
// page2.js
(function () {
    "use strict";

    WinJS.UI.Pages.define("/pages/page2/page2.html", {
        // This function is called whenever a user navigates to this page. It
        // populates the page elements with the app's data.
        ready: function (element, options) {
            // TODO: Initialize the page here.

            var dayPlaceholder = document.querySelector("#dayPlaceholder");
            var calendar = new Windows.Globalization.Calendar();
            dayPlaceholder.innerText =
                calendar.dayOfWeekAsString();
        },

        unload: function () {
            // TODO: Respond to navigations away from this page.
        },

        updateLayout: function (element) {
            /// <param name="element" domElement="true" />

            // TODO: Respond to changes in layout.
        }
    });
})();

您已經建立並自訂頁面了。在下一個步驟中，您要讓使用者執行應用程式以瀏覽到您的頁面。

步驟 4：使用瀏覽函式在頁面之間移動

現在執行應用程式，會顯示 home.html；使用者無法瀏覽到 page2.html。協助使用者瀏覽到 page2.html 的簡單方式是從 home.html 連結到該頁面。


<!-- home.html -->
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>homePage</title>
    
    <!-- WinJS references -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>
    
    <link href="/css/default.css" rel="stylesheet" />
    <link href="/pages/home/home.css" rel="stylesheet" />
    <script src="/pages/home/home.js"></script>
</head>
<body>
    <!-- The content that will be loaded and displayed. -->
    <div class="fragment homepage">
        <header aria-label="Header content" role="banner">
            <button data-win-control="WinJS.UI.BackButton"></button>
            <h1 class="titlearea win-type-ellipsis">
                <span class="pagetitle">Welcome to NavigationAppExample!</span>
            </h1>
        </header>
        <section aria-label="Main content" role="main">
            <p>Content goes here.</p>

            <!-- A hyperlink to page2.html. -->
            <p><a href="/pages/page2/page2.html">Go to page 2.</a></p>
        </section>
    </div>
</body>
</html>

如果您執行應用程式並按一下該連結，這看似可行：應用程式會顯示 page2.html。問題是應用程式執行的是最上層瀏覽。它並不是從 home.html 移至 page2.html，而是從 default.html 移至 page2.html。

執行最上層瀏覽。

您應該做的是使用 page2.html 來取代 home.html 的內容。

瀏覽到 page2.html 的建議方式。

所幸，PageControlNavigator 控制項會讓這類瀏覽類型執行起來更加容易。PageControlNavigator 程式碼 (在您應用程式的 navigator.js 檔案中) 會為您處理 WinJS.Navigation.onnavigated 事件。當事件發生時，PageControlNavigator 會載入事件指定的頁面。

當您使用 WinJS.Navigation.navigate、WinJS.Navigation.back 或 WinJS.Navigation.forward 函式來瀏覽時，會發生 WinJS.Navigation.navigated 事件。

您需要自己呼叫 WinJS.Navigation.navigate，而不是使用超連結的預設行為。您可以使用按鈕取代連結，並使用按鈕的 click-event 處理常式呼叫 WinJS.Navigation.navigate。或者，您可以變更超連結的預設行為，讓使用者按一下連結時，應用程式會使用 WinJS.Navigation.navigate 移至連結目標。 若要這樣做，請處理超連結的 click 事件，並使用事件來停止超連結的預設瀏覽行為，然後呼叫 WinJS.Navigation.navigate 函式並將連結目標傳遞給它。方法如下：

  1. 在 home.js 檔案中，為您的超連結定義 click 事件處理常式。

    
function linkClickEventHandler(eventInfo) {

}

  2. 呼叫 preventDefault 方法以避免預設連結行為 (這會直接瀏覽到指定的頁面)。

    function linkClickEventHandler(eventInfo) {
    eventInfo.preventDefault(); 
}

  3. 抓取觸發事件的超連結。

    function linkClickEventHandler(eventInfo) {
    eventInfo.preventDefault(); 
    var link = eventInfo.target;
}

  4. 呼叫 WinJS.Navigation.navigate 函式，並將連結目標傳遞給它 (或者，您也可以傳遞描述該頁面狀態的狀態物件。如需詳細資訊，請參閱 WinJS.Navigation.navigate。)

    function linkClickEventHandler(eventInfo) {
    eventInfo.preventDefault(); 
    var link = eventInfo.target;
    WinJS.Navigation.navigate(link.href); 
}

  5. 在 home.js 的 ready 函式中，將事件處理常式附加到超連結。

        WinJS.UI.Pages.define("/pages/home/home.html", {
        // This function is called whenever a user navigates to this page. It
        // populates the page elements with the app's data.
        ready: function (element, options) {
            // TODO: Initialize the page here.
            WinJS.Utilities.query("a").listen("click", linkClickEventHandler, false); 

        }
    });

這是最後一個步驟。以下是 home.js 檔案的完整程式碼。


// home.js
(function () {
    "use strict";

    WinJS.UI.Pages.define("/pages/home/home.html", {
        // This function is called whenever a user navigates to this page. It
        // populates the page elements with the app's data.
        ready: function (element, options) {
            // TODO: Initialize the page here.
            WinJS.Utilities.query("a").listen("click", linkClickEventHandler, false); 
        
        }
    });

    function linkClickEventHandler(eventInfo) {
        eventInfo.preventDefault();
        var link = eventInfo.target;
        WinJS.Navigation.navigate(link.href);
    }


})();

執行應用程式並按一下 page2.html 的連結。以下是您看到的內容。

含 [返回] 按鈕的 page2.html 畫面

這次是使用適當的瀏覽模式來顯示頁面。

瀏覽到 page2.html 後的內容解析。

頁面控制項範本包含了 [返回] 按鈕，在您使用 WinJS.Navigation 函式瀏覽時就會啟用。當您使用 WinJS.Navigation 函式時，應用程式會為您儲存瀏覽記錄。 您可以使用該瀏覽記錄，藉由呼叫 WinJS.Navigation.back 向後瀏覽，或是呼叫 WinJS.Navigation.forward 向前瀏覽。

注意  Windows 市集應用程式通常使用兩個瀏覽模式 (單層和階層式) 的其中一個模式。我們建議您不要在單層瀏覽應用程式中使用 BackButton 物件。如需詳細資料，請參閱瀏覽模式。

 

在您的應用程式暫停時儲存瀏覽記錄

您的應用程式暫停或關閉時並不會自動儲存瀏覽記錄，但是您可以輕鬆地自行儲存這個資訊。使用 WinJS.Navigation.history 屬性擷取瀏覽記錄，然後使用 WinJS.Application.sessionState 物件儲存它。 為了確保擁有順暢的暫停/繼續的使用經驗，最好在每次使用者瀏覽時就儲存這個資訊。

當應用程式繼續的時候，請從 WinJS.Application.sessionState 物件擷取記錄資訊，並用它來設定 WinJS.Navigation.history 屬性。

如需如何使用 WinJS.Application.sessionState 物件儲存和還原工作階段資料的範例，請參閱第二部分：管理應用程式週期與狀態。如需暫停與繼續的詳細資訊，請參閱啟動、繼續及多工處理。

摘要

您已經了解如何使用 WinJS.UI.Pages 命名空間的物件和方法來支援單頁瀏覽模型。

您已經了解如何使用單頁瀏覽模型來建置應用程式。同時使用範本提供的 PageControlNavigator 類別，使用 PageControl 物件和 WinJS.Navigation 功能，在您自己的應用程式實作這個模型。

相關主題

適用於開發人員

您的第一個應用程式 - 第三部分：PageControl 物件與瀏覽

新增應用程式列

快速入門：新增瀏覽列 (NavBar)

快速入門：針對配置和瀏覽使用 Hub 控制項

WinJS.Navigation Namespace

WinJS.UI.Hub object

WinJS.UI.AppBar object

WinJS.UI.NavBar object

WinJS.UI.BackButton object

HTML Hub 控制項範例

HTML AppBar 控制項範例

HTML NavBar 控制項範例

瀏覽和瀏覽歷程記錄範例

適用於設計者

瀏覽模式

命令模式

配置

返回按鈕

Hub 控制項的指導方針

應用程式列的指導方針 (Windows 市集應用程式)

設計無障礙應用程式列