Краткое руководство. Закрепление вспомогательной плитки (HTML)
[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. При разработке приложений для Windows 10 см. раздел последняя документация]
Примечание Не используете JavaScript? Перейдите к разделу Краткое руководство. Закрепление вспомогательной плитки (XAML).
В этом разделе описаны шаги по созданию вспомогательной плитки для приложения и ее закреплению на начальном экране.
Необходимые условия
Чтобы понять изложенное в этом разделе, вам понадобится:
- Практические знания концепций и терминов вспомогательных плиток. Дополнительные сведения см. в разделе Обзор вспомогательных плиток.
- Умение создавать простые приложения Магазина Windows на JavaScript с помощью API среды выполнения Windows. Дополнительные сведения см. в разделе Создание первого приложения Магазина Windows на JavaScript.
- Представление об использовании Microsoft Visual Basic для создания кода приложения Магазина Windows на HTML.
Важно Чтобы увидеть код из этого раздела в полном образце, см. Пример Secondary tiles. Пример предоставляется в версиях на 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. Предоставление уникального идентификатора вспомогательной плитке
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).
Перед закреплением вспомогательной плитки необходимо установить некоторые свойства. Попытка закрепить вспомогательную плитку без одного или нескольких из этих свойств завершится ошибкой. Требуемые свойства:
- Уникальный идентификатор плитки
- Краткое имя (только Windows 8.0)
- Отображаемое имя
- Строка аргументов, которая передается в родительское приложение при активации вспомогательной плитки
- Изображение для логотипа
- Параметры плитки (только Windows 8.0)
В этом примере строки аргумента передается время закрепления вспомогательной плитки на начальном экране.
Примечание В Windows Phone 8.1 отображаемое имя никогда не отображается на средней вспомогательной плитке (размер 150 x 150 пикселей). Кроме того, все плитки на телефоне первоначально закрепляются как средние, и поэтому на телефоне параметр newTileDesiredSize не учитывается.
Примечание Если вы предоставите тот же идентификатор, что и у существующей вспомогательной плитки, существующая вспомогательная плитка будет перезаписана.
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 на вспомогательной плитке среднего размера (150 x 150 пикселей) не отображаются ни маленький логотип, ни отображаемое имя, а также нельзя указать цвет текста переднего плана. Поэтому на телефоне не учитываются свойства, заданные в этом примере.
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 из примера Secondary tiles.
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. Создание функции открепления
Если вспомогательная плитка уже закреплена, кнопка закрепления становится кнопкой открепления, и обработчик события нажатия кнопки открепляет плитку. Данный пример предоставляет функцию, которую обработчик вызовет для открепления плитки. В качестве параметров функция принимает объект кнопки закрепления (для того, чтобы разместить всплывающий элемент подтверждения) и уникальный идентификатор вспомогательной плитки. Как и в функции закрепления, вызов открепления возвращает объект Promise.
Примечание Любую вспомогательную плитку также можно открепить через панель приложения на начальном экране. Для открепления можно полагаться на этот метод, что позволяет не трудиться над реализацией функции открепления или предоставлением кнопки открепления.
Примечание В 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 как при успехе, так и при сбое операций закрепления или открепления. В случае успеха операции кнопка переключится между закреплением и откреплением. В случае сбоя операции кнопка останется в прежнем состоянии. В обоих случаях необходимо вызвать эту функцию, чтобы вернуть свойство 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 канала, который обеспечивает связь со вспомогательной плиткой. Подробнее см. в статье Краткое руководство: отправка уведомления на вспомогательную плитку.
Связанные разделы
Краткое руководство: отправка уведомления на вспомогательную плитку