快速入门：固定辅助磁贴 (HTML)

2015-12-11

[ 本文适用于编写 Windows 运行时应用的 Windows 8.x 和 Windows Phone 8.x 开发人员。如果你要针对 Windows 10 进行开发，请参阅最新文档 ]

注意不使用 JavaScript？请参阅快速入门：固定辅助磁贴 (XAML)。

本主题指导你完成为应用创建辅助磁贴并将它固定到“开始”屏幕的步骤。

先决条件

要理解本主题，你将需要：

对辅助磁贴术语及概念的应用知识。有关详细信息，请参阅辅助磁贴概述。
能够使用 Windows 运行时 API 创建使用 JavaScript 的基本 Windows 应用商店应用。有关详细信息，请参阅创建第一个采用 JavaScript 的 Windows 应用商店应用。
了解如何使用 Microsoft Visual Basic 为基于 HTML 的 Windows 应用商店应用创建代码。

要点要查看本主题中所提供代码的完整示例，请参阅辅助磁贴示例。此示例分别以 JavaScript、C#、C++ 和 Visual Basic 版本提供。

说明

1. 添加带有固定/解锁按钮的应用栏

在 Windows 上，你通常会通过应用栏中的“固定到‘开始’屏幕”按钮为用户提供固定机会。有关如何创建应用栏的信息，请参阅快速入门：通过命令添加应用栏.

注意对于 Windows Phone 应用商店应用，通常会通过上下文菜单而不是应用栏上的按钮来完成固定操作。

以下示例将声明带有按钮的应用栏。该代码将添加到项目中的 .html 页面，本主题中的其他代码将应用到该项目。


<div id="pinUnpinFromAppbar" data-win-control="WinJS.UI.AppBar" data-win-options="">
    <button 
        data-win-control="WinJS.UI.AppBarCommand" 
        data-win-options="{id:'commandButton',section:'global'}">
    </button>
</div>

2. 为辅助磁贴提供唯一的 ID


var appbarTileId = "MySecondaryTile";

3. 创建用于将按钮设置为固定或解锁的函数

你的固定按钮的操作会在固定辅助磁贴和解锁辅助磁贴之间切换。在该示例中，我们创建用于对按钮进行相应设置的函数，并会使用系统提供的图标以实现和其他应用一致的外观。每次打开应用栏并成功固定/解锁之后，此函数将立即作为应用初始化代码的一部分进行调用。

此函数中的最后一行将应用栏的 WinJS.UI.sticky 属性设置为 false，这将允许取消应用栏。


function setAppbarButton() {
    var commandButton = appBar.getCommandById("commandButton").winControl;

    if (Windows.UI.StartScreen.SecondaryTile.exists(appbarTileId)) {
        commandButton.label = "Unpin from Start";
        commandButton.icon = "unpin";
    } else {
        commandButton.label = "Pin to Start";
        commandButton.icon = "pin";
    }

    document.getElementById("pinUnpinFromAppbar").winControl.sticky = false;
}

4. 显示相应的按钮并分配按钮单击处理程序

在本示例中，作为应用初始化的一部分，我们从最后一步使用 setAppbarButton 函数，以检查是否已固定辅助磁贴并相应地设置了按钮文本。

然后，我们将处理程序 appbarButtonClicked 分配到固定按钮的 click 事件。在下一步中，我们会向你展示如何实现事件处理程序。

每次启动应用时，作为应用初始化的一部分，此步骤中显示的代码以及你需要执行的任何其他初始化都会进行调用。


document.getElementById("pinUnpinFromAppbar").disabled = false;
setAppbarButton();

id("commandButton").addEventListener("click", appbarButtonClicked, false);

5. 在按钮的事件处理程序中创建和固定辅助磁贴

下面的示例实现一个可以由固定按钮的单击事件处理程序调用的函数。下面的函数收集几个导致固定请求的步骤：

分配创建辅助磁盘所需的属性值
创建辅助磁贴对象
指定辅助磁贴的其他属性
获取用来显示确认浮出控件的屏幕坐标（仅适用于 Windows）

必须先设置辅助磁贴的一些属性才能固定辅助磁贴。如果你尝试固定不具备上述一个或多个属性的辅助磁贴，则尝试将失败。以下为所需的属性：

磁贴的唯一 ID
短名称（仅适用于 Windows 8.0）
显示名称
激活辅助磁贴时传递到父应用程序的参数字符串
徽标图像
磁贴选项（仅适用于 Windows 8.0）

作为一个示例参数字符串，该示例传递将辅助磁贴固定到“开始”屏幕的时间。

注意在 Windows Phone 8.1 上，显示名称从不在中等 (150x150) 辅助磁贴上显示。此外，所有手机磁贴最初都会以中等磁贴的形式进行固定，因此会在手机上忽略 newTileDesiredSize 参数。

注意如果提供的 ID 与现有辅助磁贴的 ID 相同，则会覆盖现有辅助磁贴。


var currentTime = new Date();
var appbarTileId = "SecondaryTile.AppBar";
var newTileDisplayName = "Secondary tile pinned through app bar";                       
var TileActivationArguments = appbarTileId + " was pinned at " + currentTime;                        
var square150x150Logo = new Windows.Foundation.Uri("ms-appx:///Images/square150x150Tile-sdk.png");
var newTileDesiredSize = Windows.UI.StartScreen.TileSize.square150x150;

接着，创建辅助磁贴对象。此版本的构造函数会创建一个中等磁贴。请注意，如果辅助磁贴接收通知，则这是声明所有磁贴大小的最佳做法。可通过 SecondaryTileVisualElements 类提供徽标图像完成此操作。


var tile = new Windows.UI.StartScreen.SecondaryTile(appbarTileId,
                                                    newTileDisplayName,
                                                    TileActivationArguments,
                                                    square150x150Logo,
                                                    newTileDesiredSize);

此时，你拥有了一个辅助磁贴对象，可以指定未通过构造函数设置的辅助磁贴属性了。该示例指定了前景文本颜色和小徽标，并指定在磁贴上展示显示名称。

注意在 Windows Phone 8.1 上，不会在中等 (150x150) 辅助磁贴上显示小徽标或显示名称，并且不能指定前景文本颜色，因此会在手机上忽略此示例中设置的这些属性。


tile.visualElements.showNameOnSquare150x150Logo = true;                        
tile.visualElements.foregroundText = Windows.UI.StartScreen.ForegroundText.light;
tile.visualElements.square30x30Logo = new Windows.Foundation.Uri("ms-appx:///Images/square30x30Tile-sdk.png");

在 Windows 上，用户必须在固定辅助磁贴之前进行确认。在确认对话框中，用户可以替代磁贴的显示名称，并从各种要固定的磁贴大小之间进行选择。确认浮出控件应该显示在调用固定请求的按钮旁边。此示例将检索固定按钮的边界矩形，并指定确认对话框应显示在该按钮上方。

注意在 Windows Phone 8.1 上，不会向用户显示确认对话框，磁贴会直接以中等磁贴的形式固定到“开始”屏幕，并且没有显示名称。将忽略此处显示的代码。


var element = document.getElementById("commandButton");
var selectionRect = element.getBoundingClientRect();
var buttonCoordinates = { x: selectionRect.left, y: selectionRect.top, width: selectionRect.width, height: selectionRect.height };
var placement = Windows.UI.Popups.Placement.above;

接着，此函数请求将辅助磁贴固定。

在 Windows Phone 8.1 上，该调用将固定磁贴、暂停应用并将用户转到“开始”屏幕。
在 Windows 上，该调用会显示一个要求用户允许固定磁贴的确认浮出控件。下面的示例使用固定按钮的边界矩形，在这些坐标的上方显示确认弹出窗口。得到用户批准后，Windows 会创建辅助磁贴并将其放置在“开始”屏幕上。用户仍位于应用中。


return new WinJS.Promise(function (complete, error, progress) {
    tile.requestCreateForSelectionAsync(buttonCoordinates, placement).done(function (isCreated) {
        if (isCreated) {
            complete(true);
        } else {
            complete(false);
        }
    });
});

注意在 Windows Phone 8.1 上，对 RequestCreateAsync 或 RequestCreateForSelectionAsync 的调用将退出应用应用并将用户转到“开始”屏幕。因此，不会执行 RequestCreateAsync 或 RequestCreateForSelectionAsync 调用之后的任何代码。因此，在 Windows Phone 8.1 项目中，你应该侦听 Suspending 事件，以便执行需要在应用退出前完成的所有操作，例如保存应用状态。

此处将显示来自辅助磁贴示例的完整 appbarButtonClicked 和 pinByElementAsync 函数。


function appbarButtonClicked() {
    document.getElementById("pinUnpinFromAppbar").winControl.sticky = true;

    if (WinJS.UI.AppBarIcon.unpin === document.getElementById("commandButton").winControl.icon) {
        unpinByElementAsync(document.getElementById("commandButton"), appbarTileId).done(function (isDeleted) {
            if (isDeleted) {
                WinJS.log && WinJS.log("Secondary tile was successfully unpinned.", "sample", "status");
                setAppbarButton();
            } else {
                WinJS.log && WinJS.log("Secondary tile was not unpinned.", "sample", "error");
                setAppbarButton();
            }
        });
    } else {
        pinByElementAsync(document.getElementById("commandButton"), appbarTileId, "Appbar pinned secondary tile").done(function (isCreated) {
            if (isCreated) {
                WinJS.log && WinJS.log("Secondary tile was successfully pinned.", "sample", "status");
                setAppbarButton();
            } else {
                WinJS.log && WinJS.log("Secondary tile was not pinned.", "sample", "error");
                setAppbarButton();
            }
        });
    }
}                        
                        
function pinByElementAsync(element, newTileID, newTileDisplayName) {

    var square150x150Logo = new Windows.Foundation.Uri("ms-appx:///Images/square150x150Tile-sdk.png");
    var square30x30Logo = new Windows.Foundation.Uri("ms-appx:///Images/square30x30Tile-sdk.png");

    var currentTime = new Date();
    var TileActivationArguments = newTileID + " was pinned at=" + currentTime;

    var tile = new Windows.UI.StartScreen.SecondaryTile(newTileID,
                                                        newTileDisplayName,
                                                        TileActivationArguments,
                                                        square150x150Logo,
                                                        Windows.UI.StartScreen.TileSize.square150x150);
                                                        
    tile.visualElements.foregroundText = Windows.UI.StartScreen.ForegroundText.light;
    tile.visualElements.square30x30Logo = square30x30Logo;
    tile.visualElements.showNameOnSquare150x150Logo = true;

    var selectionRect = element.getBoundingClientRect();

    return new WinJS.Promise(function (complete, error, progress) {
        tile.requestCreateForSelectionAsync({ x: selectionRect.left, y: selectionRect.top, width: selectionRect.width, height: selectionRect.height }, Windows.UI.Popups.Placement.above).done(function (isCreated) {
            if (isCreated) {
                complete(true);
            } else {
                complete(false);
            }
        });
    });
}

6. 创建 unpin 函数

当辅助磁贴已经固定后，固定按钮会变成未固定按钮，此按钮的 click 事件处理程序会取消固定辅助磁贴。下面的示例提供的函数将由该处理程序调用以取消辅助磁贴。此函数接受固定按钮对象作为参数，而且为了放置确认弹出窗口，还接受辅助磁贴的唯一 ID。正如在固定函数中一样，取消固定调用返回 Promise 对象。

注意任何辅助磁盘还可以通过“开始”屏幕应用栏取消固定。你可以选择依赖这种取消固定方法，在这种情况下，你不需要实现取消固定功能，也不需要提供 unpin 按钮。

注意在 Windows Phone 8.1 上，不会要求用户确认是否将辅助磁贴解锁。在手机上将辅助磁贴解锁的过程与将其他任何磁贴解锁的过程相同。将忽略此处显示的代码。


function unpinByElementAsync(element, unwantedTileID) {

    var selectionRect = element.getBoundingClientRect();
    var buttonCoordinates = { x: selectionRect.left, y: selectionRect.top, width: selectionRect.width, height: selectionRect.height };
    var placement = Windows.UI.Popups.Placement.above;

    var tileToDelete = new Windows.UI.StartScreen.SecondaryTile(unwantedTileID);
    
    return new WinJS.Promise(function (complete, error, progress) {
        tileToGetDeleted.requestDeleteForSelectionAsync(buttonCoordinates, placement).done(function (isDeleted) {
            if (isDeleted) {
                complete(true);
            } else {
                complete(false);
            }
        });
    });
}

7. 实现按钮的事件处理程序

当用户选择应用栏上的按钮时，会显示一个要求用户确认的弹出窗口。若要确保在显示弹出窗口时不取消应用栏，必须设置应用栏的 WinJS.UI.sticky 属性。此外，还要确保正确分配了弹出窗口的父级。下面的示例调用我们在以前的步骤中定义的 setAppbarButton、pinByElementAsync 和 unpinByElementAsync 函数。

请注意，在固定和取消固定操作完成之后，该处理程序会针对成功和失败两种情况都调用 setAppbarButton。如果操作成功，该按钮会在 pin 和 unpin 之间切换。如果操作失败，该按钮将保持原样。在这两种情况下，都必须调用该函数以将 WinJS.UI.sticky 属性恢复为 false，从而使应用栏可以取消。


function appbarButtonClicked() {
    document.getElementById("pinUnpinFromAppbar").winControl.sticky = true;

    if (WinJS.UI.AppBarIcon.unpin === document.getElementById("commandButton").winControl.icon) {
        unpinByElementAsync(document.getElementById("commandButton"), appbarTileId).done(function (isDeleted) {
            if (isDeleted) {
                WinJS.log && WinJS.log("Secondary tile was successfully unpinned.", "sample", "status");
                setAppbarButton();
            } else {
                WinJS.log && WinJS.log("Secondary tile was not unpinned.", "sample", "error");
                setAppbarButton();
            }
        });
    } else {
        pinByElementAsync(document.getElementById("commandButton"), appbarTileId, "App bar pinned secondary tile", "A secondary tile that was pinned by the user from the app bar").done(function (isCreated) {
            if (isCreated) {
                WinJS.log && WinJS.log("Secondary tile was successfully pinned.", "sample", "status");
                setAppbarButton();
            } else {
                WinJS.log && WinJS.log("Secondary tile was not pinned.", "sample", "error");
                setAppbarButton();
            }
        });
    }
}

摘要和后续步骤

在本快速入门中，你在应用栏上定义了一个可供用户固定或取消固定辅助磁贴的按钮。你创建了辅助磁贴、定义了它的很多属性并且向用户提供了导致最终向“开始”屏幕中添加辅助磁贴的确认对话框。

固定辅助磁贴后，父应用磁贴会创建一个频道统一资源标识符 (URI) 以便它可以与该辅助磁贴进行通信。有关详细信息，请参阅快速入门：向辅助磁贴发送通知。

通过