共用方式為

如何將 Microsoft 服務新增到您的應用程式 (HTML)

  • 發行項

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

您可以在此處了解如何將 Microsoft 服務的功能新增到您的 Windows 執行階段應用程式，讓應用程式可以存取使用者在 Microsoft OneDrive 中的個人檔案資訊、檔案和相片，以及 Outlook.com 資訊。 本教學課程中的步驟是從一個完全空白的應用程式開始，然後新增功能以登入使用者的 Microsoft 帳戶，再取得使用者的個人檔案資訊，顯示在應用程式中。

重要  本主題中的教學課程將示範 Windows 市集應用程式。您也可以將 Microsoft 服務新增到 Windows Phone 市集應用程式。不過，由於 Windows Phone 使用者介面並不支援飛出視窗，因此您必須使用 Windows Phone 市集應用程式中的頁面來實作本主題中所使用之飛出視窗所屬的功能。

 

您必須知道的事

技術

先決條件

  • Windows 8
  • Microsoft Visual Studio
  • Live SDK
  • Windows 市集開發人員帳戶
  • 兩個影像檔 (PNG 格式) 在應用程式中使用

指示

步驟 1: 建立 [空白應用程式] 專案並包含 Live SDK

從 Visual Studio 範本建立您的新應用程式，步驟如下：

  1. 從 Visual Studio 的 [檔案] 功能表，按一下 [新增專案...]****
  2. 在 [新增專案...] 對話方塊中，移至 [已安裝的]**** > [範本] > [JavaScript]**** > [Windows 市集]。
  3. 選取 [空白應用程式]****。
  4. 輸入新應用程式的名稱和位置，然後按一下 [確定]。
  5. 建置並測試您的應用程式。此時應該啟動並出現一個只顯示 [內容在此處出現]**** 的空白頁面。如果看到此頁面，請關閉應用程式並繼續。

步驟 2: 將應用程式新增到您的 Windows 市集開發人員帳戶

應用程式必須在 Windows 市集開發人員帳戶登錄，才能使用 Live SDK 存取的雲端服務。您不需要將應用程式提交到 Windows 市集進行認證。您只需要在您的 Windows 市集開發人員帳戶中輸入其名稱。

步驟 3: 新增應用程式資料和設定飛出視窗

使用 Live SDK 的 Windows 市集應用程式至少必須執行下列兩項：

  • 允許使用者登入他們的 Microsoft 帳戶，以及登出 (如果可行)。
  • 顯示隱私權原則，說明如何保護您的應用程式將存取的個人資料。

如需有關登入和登出體驗及隱私權原則的詳細資訊，請參閱 Microsoft 帳戶登入的需求。

在 Windows 市集應用程式中，這些可透過 [設定] 飛出視窗來存取。

若要將飛出視窗新增到您的應用程式，請執行下列各項：

  1. 建立 [帳戶] 飛出視窗頁面。

    1. 為 [帳戶]**** 飛出視窗檔案建立新資料夾。在 [方案總管] 中，用滑鼠右鍵按一下專案名稱，選取 [加入]****，然後選取 [新增資料夾]。

    2. 將新資料夾重新命名為 account。

    3. 用滑鼠右鍵按一下 [account] 資料夾，選取 [加入]****，然後選取 [新增項目...]

    4. 在 [加入新項目]**** 對話方塊中，移至 [已安裝的] > [JavaScript]**** > [Windows 市集]，然後選取 [頁面控制項]****。

    5. 在 [名稱] 欄位中，輸入 "account.html"，然後按一下 [加入]****。

    6. 修改應用程式的新檔案。

      在 account.html 檔案中，以此程式碼取代 <div> 元素。

       <div id="account" data-win-control="WinJS.UI.SettingsFlyout" data-win-options="{width: 'narrow'}">
    <div class="SettingsPane">
        <div class="win-label">
            <button onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton">
            </button>
            <span class="SettingsTitle">Account</span>
        </div>
        <article class="SettingsContent">
            <p id="accountPrompt"></p>
        </article>
        <div>
            <!-- define one button to sign in and another to sign out, but show only  -->
            <!-- one at a time, depending on whether the user is currently signed in or not. -->
            <button id="signInBtn" onclick="signInCmd()" style="display: none">Sign in</button>
            <button id="signOutBtn" onclick="signOutCmd()" style="display: none">Sign out</button>
        </div>
     </div>
</div>

      將下列程式碼新增至 account.css 檔案的結尾。

      .account p {
    margin-left: 120px;
}

.SettingsPane {
    margin-top:36px;
    margin-left:48px;
}

.SettingsTitle {
    margin-left: 36px;
}

.SettingsContent {
     margin-top: 24px;
}

#account {
      background-color: gray ; 
}

  2. 建立 [隱私權] 飛出視窗頁面。

    1. 為 [隱私權]**** 飛出視窗檔案建立新資料夾。在 [方案總管] 中，用滑鼠右鍵按一下專案名稱，選取 [加入]****，然後選取 [新增資料夾]。

    2. 將新資料夾重新命名為 privacy。

    3. 用滑鼠右鍵按一下 [privacy] 資料夾，選取 [加入]****，然後選取 [新增項目...]

    4. 在 [加入新項目]**** 對話方塊中，移至 [已安裝的] > [JavaScript]**** > [Windows 市集]，然後選取 [頁面控制項]****。

    5. 在 [名稱] 欄位中，輸入 "privacy.html"，然後按一下 [加入]****。

    6. 修改應用程式的新檔案。

      在 privacy.html 檔案中，以此程式碼取代 <div> 元素。

      <div id="privacy" data-win-control="WinJS.UI.SettingsFlyout" data-win-options="{width: 'narrow'}">
    <div class="SettingsPane">
        <div class="win-label">
            <button onclick="WinJS.UI.SettingsFlyout.show()" class="win-backbutton">
            </button>
            <span class="SettingsTitle">Privacy</span>
        </div>
        <article class="SettingsContent">
            <!-- Customize this text to fit your application.  -->
            <h2>How we protect your personal information</h2>
            <h4>Your privacy statement or a link to your privacy statement goes here.</h4>
        </article>
    </div>
</div>

      務必變更 privacy.html 的內容，才能參照到您的隱私權聲明。

      將下列程式碼新增至 account.css 檔案的結尾。

      .privacy p {
    margin-left: 120px;
}

.SettingsPane {
    margin-top:36px;
    margin-left:48px;
}

.SettingsTitle {
    margin-left: 36px;
}

.SettingsContent {
     margin-top: 24px;
}

#privacy {
      background-color: gray ; 
}

  3. 新增設定命令。

    在 default.js 檔案中，將此程式碼新增到 app.onactivated 事件處理常式。

    // Define the Settings flyout commands.
// The commands appear in the Settings charm from top-to-bottom
//  in the order they are added.
app.onsettings = function (e) {
    e.detail.applicationcommands = {
        // Add the Account command
        "account": {
            // Location of page content
            href: "/account/account.html",
            // Command to show in settings menu
            title: "Account"
        },
        // Add the privacy command.
        "privacy": {
             // Location of page content
             href: "/privacy/privacy.html",
             // Command to show in settings menu
             title: "Privacy"
        }
    }

    // Command to update app's settings menu
    //  using the preceding definition.
    WinJS.UI.SettingsFlyout.populateSettings(e);
}

  4. 建置並執行應用程式。

  5. 開啟設定常用鍵。確認 [帳戶] 和 [隱私權]**** 命令出現在 [設定] 窗格中。

  6. 按一下每一個命令，確認會開啟飛出視窗。

    看到兩個飛出視窗後，關閉您的應用程式並繼續。

步驟 4: 新增 UI 內容和資料繫結

您會希望應用程式的 UI 是呈現連線到使用者 Microsoft 帳戶的目前狀態。所以不要在應用程式的 UI 使用靜態文字，改用資料繫結，讓 UI 內容在對應的資料值變更時隨之變更。

在此步驟中，您要新增程式碼，將應用程式的資料連線到 UI。

  1. 更新 default.html 以加入含有繫結屬性的 UI 元素，將 UI 與應用程式資料連結。

    若要這樣做，以此程式碼取代 default.html 中的 <body> 標記內容。

    <div id="bindingDiv">
  <!-- The elements in this div get their data from the app's data
       object by using a binding object. -->
  <div class="heading">
    <h1>
      <!-- The app's title. This is configured by the program. -->
      <span id="titleText" data-win-bind="innerText: person.titleText">person.titleText</span>
    </h1>
  </div>
  <div class="content">
    <!-- The app's content. This is a photo for this example. 
         When the user is signed out, one photo is shown;
         when they are signed in, another is shown.           -->
    <img id="appImage" data-win-bind="src: image.url; title: image.caption" />
    <!-- Show the caption as text in the display as well as hover text in the image. -->
    <p id="appImageCaption" data-win-bind="innerText: image.caption">image.caption</p>
  </div>
</div>

    在包含 data-win-bind 屬性的標記中，繫結到屬性的資料欄位也會顯示在標記的值中。這麼做只是為了偵錯之用。如果繫結成功，程式的資料值就會取代這個文字。如果繫結不成功，您會看到未顯示在 UI 中的資料值名稱，這可用於協助您偵錯。

  2. 建立資料物件做為繫結物件之用。

    在專案的 js 資料夾中建立名為 data.js 的新檔案，然後加入程式碼。若要這樣做：

    1. 在 [方案總管] 中，用滑鼠右鍵按一下 js 資料夾，選取 [加入]****，然後選取 [新增項目...]。

    2. 移至 [已安裝的]**** > [JavaScript] > [程式碼]****，然後選取 [JavaScript 檔案]。

    3. 在 [名稱]**** 欄位中，輸入 "data.js"，然後按一下 [加入]。

    4. 以此範例中的程式碼取代 data.js 的內容。

      (function () {

    "use strict";

    // The global data object used to reference the binding object
    WinJS.Namespace.define("binding",
        {
            Person: null
        }
    );

    // Static text
    WinJS.Namespace.define("display",
        {
            state: ["Some nice photo", "'s favorite photo"]
        }
    );

    // The app's data object that is used to map the
    //  sign-in state to the UI.
    WinJS.Namespace.define("appInfo",
        {
            index: 0,       // The sign-in state.
            image: {
                // The image to show
                url: "/images/SignedOutImage.png",
                caption: "Something not so special."
            },
            person: {
                // The info about the user
                userName: null,
                titleText: display.state[0]
            }
        }
   );

})();

  3. 透過在參考 default.js 的 <script> 標記之前輸入此程式碼，在 default.html 新增此新檔案的參考。

    
<!-- The app's data definition -->
<script src="/js/data.js"></script>

  4. 新增程式碼，將資料物件繫結到 UI。

    在 default.js 的 app.onactivated 事件處理常式中，新增此程式碼以建立繫結物件並將物件初始化。

    // Create the binding object that connects the appInfo data
//  to the app's UI.
binding.Person = WinJS.Binding.as(appInfo);

// Update the binding object so that it reflects the state
//  of the app and updates the UI to reflect that state.
getInfoFromAccount(binding.Person);

  5. 新增事件處理常式，在應用程式的文件載入之後，使用繫結物件的資料更新 UI。

    在 default.js 中的 app.oncheckpoint 指派之前，新增此事件處理常式。

    app.onloaded = function (args) {
    // Initialize the UI to match the corresponding data object.
    var div = document.getElementById("bindingDiv");
    WinJS.Binding.processAll(div, appInfo);
}

  6. 新增會同步處理應用程式資料與使用者資料的函式。

    在此步驟中，這個函式只會提供用於測試的靜態資料。從 Microsoft 帳戶取得使用者資料的函式會在後續步驟新增。

    在 default.js 中，在匿名函式之後新增此函式，這樣應用程式中的其他模組便能夠看見此函式。

    function getInfoFromAccount(p) {
    // Test for a parameter and assign the unbound data object
    //  if a parameter wasn't passed. This doesn't refresh the binding
    //  object, but it does keep the data object coherent with the
    //  sign-in state.
    if (undefined === p) { p = appInfo; }

    if (0 == p.index) {
        // The program executes this branch when the user is 
        // not signed in.

        // Set the data to the signed-out state values
        //   and update the app title.
        p.person.userName = null;
        p.person.titleText = display.state[p.index];

        // These elements are the default values to show
        //  when the user is not signed in.
        p.image.url = "/images/SignedOutImage.png";
        p.image.caption = "Something not so special.";
    }

    if (1 == p.index) {
        // The program executes this branch when the user is 
        //  signed in.

        // Set the data to the signed-in state,
        //  get the user's first name, and update the app title.
        p.person.userName = "Bob";
        p.person.titleText = p.person.userName + display.state[p.index];

        // These elements would normally be read from the user's data,
        //  but in this example, app resources are used.
        p.image.url = "/images/SignedInImage.png";
        p.image.caption = "Something special to me.";
    }
}

  7. 新增您的影像檔。

    1. 將這兩個影像檔複製到專案中的 [影像] 資料夾。將一個影像重新命名為 "SignedOutImage.png"，另一個重新命名為 "SignedInImage.png"。

    2. 在 [方案總管]**** 中，用滑鼠右鍵按一下 [影像] 資料夾，依序選取 [加入]**** > [現有項目...]。

    3. 選取剛才加入的兩個影像檔，然後按一下 [加入]****。

  8. 建置並測試您的應用程式。如果頁面顯示正確的文字和 SignedOutImage.png 影像，請繼續下一步驟。

    如果應用程式顯示資料欄位的名稱而不是文字，表示資料繫結發生問題，您需要先修正才能繼續。

步驟 5: 更新 [帳戶] 飛出視窗以使用繫結物件

  1. 在 account.html 中，將 <button> 標記變更成像這樣，登入狀態才能用來在飛出視窗顯示正確的按鈕。

    
<button id="signInBtn" onclick="signInCmd(binding.Person)" style="display:none">Sign in</button>
<button id="signOutBtn" onclick="signOutCmd(binding.Person)" style="display:none">Sign out</button>

  2. 在 account.js 中，將這些函式新增到匿名函式之後。

    function updateDisplay(p) {
    // Update the display to show the caption text and button
    // that apply to the current sign-in state.

    // Test for a parameter and assign the unbound global data object
    //  if a parameter wasn't passed. This doesn't refresh the screen
    //  but it does keep the data object coherent.
    if (undefined === p) { p = appInfo; }

    // Get the elements in the display for this function to update.
    var prompt = document.getElementById("accountPrompt");
    var inBtn = document.getElementById("signInBtn");
    var outBtn = document.getElementById("signOutBtn");

    // Update the elements to show the correct text and button for the
    //  the sign-in state.
    if (0 == p.index)  {
        // The user is signed out, so prompt them to sign in.
        prompt.innerText = "Sign in to see your favorite photo."
        outBtn.style.display = "none";
        inBtn.style.display = "block";
    } else {
        // The user is signed in so welcome them and show the sign-out button.
        prompt.innerText = "Welcome, " + p.person.userName + "!"
        inBtn.style.display = "none";
        outBtn.style.display = "block";
    }
}

function signInCmd(p) {
    // Sign the new user in.
    //  This call closes the Flyout and Settings charm.
    SignInNewUser(p);

    // Update the display to the signed-in state but keep the Flyout open
    // in case they want to sign in again.
    updateDisplay(p);

    // Return to the Settings flyout.   
    WinJS.UI.SettingsFlyout.show();
}

function signOutCmd(p) {
    // Sign the current user out.
    SignOutUser(p);
    // Update the display to the signed-out state but keep the Flyout open
    // in case they want to sign in again.
    updateDisplay(p);

    // Return to the Settings flyout.   
    WinJS.UI.SettingsFlyout.show();
}

    然後修改 WinJS.UI.Pages.define 呼叫在 ready 狀況的函式，以便包含對 updateDisplay 的呼叫，如同此範例。

    ready: function (element, options) {
  // TODO: Initialize the page here.

  // Update the Account Flyout to reflect 
  //  the user's current sign-in state.
  updateDisplay(binding.Person);
},

  3. 在 default.js 新增函式，將使用者登入和登出他們的 Microsoft 帳戶。

    這些函式不會與「Windows Live 服務」功能互動—目前還不行。但會在後續步驟中新增。這些函式只能讓您測試繫結物件，確定物件可以在登入狀態以及當登入狀態變更要更新 UI 時運作。

    function SignInNewUser(p) {
    // Sign the user in.

    // Test for a parameter and assign the unbound global data object
    //  if a parameter wasn't passed. This doesn't refresh the screen
    //  but it does keep the data object coherent.
    if (undefined === p) { p = appInfo; }

    p.index = 1;

    getInfoFromAccount(p);
}

function SignOutUser(p) {
    // Sign the user out.

    // Test for a parameter and assign the unbound global data object
    //  if a parameter wasn't passed. This doesn't refresh the screen
    //  but it does keep the data object coherent.
    if (undefined === p) { p = appInfo; }

    p.index = 0;

    getInfoFromAccount(p);
}

  4. 建置並測試您的應用程式。

    1. 您的應用程式啟動並顯示 SignedOutImage.png。

    2. 開啟設定常用鍵，選取 [帳戶] 命令。確認出現 [登入]**** 按鈕和提示。

    3. 按一下 [登入] 按鈕，確認應用程式狀態和 [帳戶] 飛出視窗內容變更，以反映登入狀態。

    4. 在 [帳戶]**** 飛出視窗，確認出現 [登出] 按鈕和提示。

    5. 按一下 [登出]**** 按鈕，確認應用程式狀態和 [帳戶] 飛出視窗內容變更，以反映登出狀態。

    當您的應用程式像這樣運作時，您就可以開始新增「Windows Live 服務」功能。

步驟 6: 新增 Live SDK 函式

  1. 將 Live SDK 的參照新增到您的應用程式。

    1. 在 [方案總管] 中，以滑鼠右鍵按一下 [參考]****，然後選取 [加入參考...]。

    2. 移至 [Windows]**** > [延伸]，選取 [Live SDK]****，然後按一下 [確定]。

    3. 在 default.html 的 <head> 標記中，在 default.css 連結前新增此行。

      <!-- The Live SDK -->
<script src="///LiveSDKHTML/js/wl.js"></script>

  2. 初始化 Live SDK。

    在 default.js 中，在 app.onactivated 處理常式的 binding.Person 指派之後輸入此程式碼。

    // Initialize the Live SDK.
WL.init();

  3. 更新 getInfoFromAccount 函式，讓您的應用程式從使用者的 Microsoft 帳戶取得他們的登入狀態。

    在 default.js 的 getInfoFromAccount 中，以此程式碼取代兩個用來測試 p.index 的 if 陳述式。

    // Call the user's Microsoft account to get the identity of the current 
//  user. If the user is signed in, the success branch runs.
//  If the user is not signed in, the failure branch runs.
WL.api({
    path: "me",
    method: "GET"
}).then(
    function (response) {
        // The program executes this branch when the user is 
        // signed in.

        // Save the app's sign-in state.
        p.index = 1;

        // Set the data to the signed-in state,
        //   get the user's first name, and update the app title.
        p.person.userName = response.first_name;
        p.person.titleText = p.person.userName + display.state[p.index];

        // These elements would normally be read from the user's data,
        // but in this example, app resources are used.
        p.image.url = "/images/SignedInImage.png";
        p.image.caption = "Something special to me.";
    },
    function (responseFailed) {
        // The program executes this branch when the user is 
        // not signed in.

        // Reset the app state.
        p.index = 0;

        // Set the data to the signed-out state values
        //   and update the app title.
        p.person.userName = null;
        p.person.titleText = display.state[p.index];

        // These elements are the default values to show
        //  when the user is not signed in.
        p.image.url = "/images/SignedOutImage.png";
        p.image.caption = "Something not so special.";
    }
);

  4. 更新 SignInNewUser 函式，將使用者登入他們的 Microsoft 帳戶。

    在 default.js 的 SignInNewUser 中，以此程式碼取代參數測試之後的程式碼。

    // Sign the user in with the minimum scope necessary for the app.
WL.login({
    scope: ["wl.signin"]
}).then(function (response) {
    getInfoFromAccount(p);
});

  5. 更新 SignOutUser 函式。

    在 default.js 的 SignOutUser 中，以此程式碼取代參數測試之後的程式碼。

    // Sign out and then refresh the app's data object.
WL.logout().then(function (response) {
    getInfoFromAccount(p);
});

  6. 新增 ShowSignOutButton 函式。

    在 default.js 結尾，新增此處所顯示的 ShowSignOutButton 函式。

    function ShowSignOutButton() {
    // Return true or false to indicate whether the user 
    // can sign out of the app.
    return (WL.canLogout());
}

  7. 新增測試，測試使用者是否可以登出。如果使用者是從與 Microsoft 帳戶相關聯的電腦帳戶登入他們的應用程式，他們無法登出應用程式。此函式是要測試這種狀況，能夠顯示正確的提示給使用者。

    在 account.js 的 updateDisplay 函式，以此程式碼取代 if 陳述式。請注意，新增此測試是為了分辨 [登出] 按鈕是否應該顯示。

        if (0 == p.index) {
        // The user is signed out, so prompt them to sign in.
        prompt.innerText = "Sign in to see your favorite photo."
        outBtn.style.display = "none";
        inBtn.style.display = "block";
    } else {
        // The user is signed in, so welcome them.
        //  If the user can sign out, show them the sign-out button.

        var promptText = "Welcome, " + p.person.userName + "!";
        var signOutBtnStyle = "block";
        if (ShowSignOutButton()) {
            // The user is signed in and can sign out later,
            //  so welcome them and show the sign-out button.
            signOutBtnStyle = "block";
        } else {
            // The user is signed in and can't sign out later,
            //  so welcome them and hide the sign-out button.
            promptText = promptText + " The app is signed in through your Windows 8 account."
            signOutBtnStyle = "none";
        }

        prompt.innerText = promptText;
        outBtn.style.display = signOutBtnStyle;
        inBtn.style.display = "none"
    }

  8. 移除先前測試使用的虛設程式碼。

    在 account.js 的 signInCmd，移除對 updateDisplay 和 WinJS.UI.SettingsFlyout.show 的呼叫，讓該函式只剩下這一行程式碼。

    // Sign the new user in.
//  This call closes the Flyout and Settings charm.
SignInNewUser(p);

    在 account.js 的 signOutCmd，移除對 updateDisplay 的呼叫，讓該函式只剩下這幾行程式碼。

    // Sign the current user out.
SignOutUser(p);

// Return to the Settings flyout.   
WinJS.UI.SettingsFlyout.show();

您的應用程式現在可以開始進行 Microsoft 帳戶的測試。

步驟 7: 測試您的應用程式

建置並執行您的應用程式，以及測試這些動作。

  1. 測試登入 Microsoft 帳戶。

    從應用程式已登出使用者的 Microsoft 帳戶開始，請嘗試這些步驟：

    1. 開啟 [設定] 飛出視窗，選取 [帳戶] 命令，然後按一下 [登入]****。
    2. 使用 Microsoft 帳戶登入。如果應用程式提示您需要權限才能繼續，按一下 [是]。
    3. 確認應用程式中的文字和圖片變更為已登入的文字和圖片。

  2. 測試從應用程式登出。

    注意  如果您要從與 Microsoft 帳戶相關聯的電腦帳戶測試您的應用程式，[登出] 按鈕將會停用。這是預期的行為。若要執行此測試，您必須從與 Microsoft 帳戶沒有關聯的電腦帳戶執行您的應用程式。

     

    從應用程式已登入使用者的 Microsoft 帳戶開始，請嘗試這些步驟：

    1. 開啟 [設定] 飛出視窗，選取 [帳戶]**** 命令，然後按一下 [登出]。
    2. 確認應用程式中的文字和圖片變更為已登出的文字和圖片。

  3. 測試單一登入。

    單一登入是 Windows 的功能，讓您將電腦帳戶與 Microsoft 帳戶相關聯。如果您是從這種電腦帳戶執行您的應用程式，應用程式的行為與上述不同。

    例如：

    • 應用程式可能自動以已登入狀態啟動。
    • [帳戶] 飛出視窗不會出現 [登出]**** 按鈕，因為您不能從應用程式內登出您的帳戶。
    • [帳戶] 飛出視窗會顯示額外的訊息，說明您不能從您的應用程式登出。

相關主題

資料繫結

data-win-control

data-win-options

data-win-bind

Live SDK

WinJS.Namespace

WinJS.UI.SettingsFlyout

WL.api

WL.canLogout

WL.init

WL.login

WL.logout