Schnellstart: Anheften einer sekundären Kachel (HTML)
[ Dieser Artikel richtet sich an Windows 8.x- und Windows Phone 8.x-Entwickler, die Windows-Runtime-Apps schreiben. Wenn Sie für Windows 10 entwickeln, finden Sie weitere Informationen unter neueste Dokumentation]
Hinweis Sie verwenden nicht JavaScript? Weitere Informationen finden Sie unter Schnellstart: Anheften einer sekundären Kachel (XAML).
Dieses Thema führt Sie durch die Schritte zum Erstellen einer sekundären Kachel für eine App und Anheften der Kachel an die Startseite.
Voraussetzungen
Die Ausführungen in diesem Thema setzen Folgendes voraus:
- Grundkenntnisse der Begriffe und Konzepte für sekundäre Kacheln. Weitere Informationen finden Sie unter Übersicht über sekundäre Kacheln.
- Kenntnisse zum Erstellen einer einfachen Windows Store-App mit JavaScript mithilfe von Windows-Runtime-APIs. Weitere Informationen finden Sie unter Erstellen Ihrer ersten Windows Store-App mit JavaScript.
- Grundkenntnisse zum Erstellen von Code für eine HTML-basierte Windows Store-App mithilfe von Microsoft Visual Basic.
Wichtig Unter Beispiel für sekundäre Kacheln wird der in diesem Thema bereitgestellte Code in einem vollständigen Beispiel angewendet. Das Beispiel wird als JavaScript-, C#-, C++- und Visual Basic-Version zur Verfügung gestellt.
Anweisungen
1. Hinzufügen einer App-Leiste mit einer Schaltfläche zum Anheften/Lösen
Normalerweise bieten Sie dem Benutzer unter Windows über die Schaltfläche An „Start“ anheften auf der App-Leiste die Möglichkeit zum Anheften. Informationen zum Erstellen einer App-Leiste finden Sie unter Schnellstart: Hinzufügen von App-Leisten mit Befehlen.
Hinweis Für Windows Phone Store-Apps geschieht das Anheften normalerweise über ein Kontextmenü und nicht über eine Schaltfläche auf einer App-Leiste.
Im folgenden Beispiel wird eine App-Leiste mit einer Schaltfläche deklariert. Dieser Code wird der HTML-Seite in Ihrem Projekt hinzugefügt, auf die sich der restliche Code in diesem Thema bezieht.
<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. Bereitstellen einer eindeutigen ID für Ihre sekundäre Kachel
var appbarTileId = "MySecondaryTile";
3. Erstellen einer Funktion zum Einrichten des Anheftens oder Lösens einer Schaltfläche
Über die Ihrer Schaltfläche zum Anheften zugewiesene Aktion wird zwischen Anheften und Lösen der sekundären Kachel umgeschaltet. In diesem Beispiel wird eine Funktion erstellt, die die Schaltfläche dementsprechend einrichtet. Dabei werden vom System bereitgestellte Symbole für eine konsistente Darstellung mit anderen Apps verwendet. Diese Funktion wird als Teil des Initialisierungscodes Ihrer App immer dann aufgerufen, wenn die App-Leiste geöffnet wird. Außerdem wird sie direkt nach jedem erfolgreichen Vorgang zum Anheften/Lösen aufgerufen.
Die letzte Zeile dieser Funktion legt die WinJS.UI.sticky-Eigenschaft der App-Leiste auf false fest, wodurch die App-Leiste geschlossen werden kann.
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. Anzeigen der entsprechenden Schaltfläche und Zuweisen eines Klick-Handlers für die Schaltfläche
In diesem Beispiel wird als Teil der App-Initialisierung die setAppbarButton-Funktion aus dem letzten Schritt verwendet, um zu prüfen, ob die sekundäre Kachel bereits angeheftet wurde, und um den Schaltflächentext entsprechend festzulegen.
Dann weisen wir den Handler appbarButtonClicked dem click-Ereignis der Schaltfläche zum Anheften zu. Im nächsten Schritt zeigen wir Ihnen die Implementierung des Ereignishandlers.
Rufen Sie den Code in diesem Schritt bei jedem Start der App zusammen mit anderen erforderlichen Initialisierungsfunktionen als Teil der Initialisierung Ihrer App auf.
document.getElementById("pinUnpinFromAppbar").disabled = false;
setAppbarButton();
id("commandButton").addEventListener("click", appbarButtonClicked, false);
5. Erstellen und Anheften der sekundären Kachel im Ereignishandler der Schaltfläche
In diesem Beispiel wird eine einzige Funktion implementiert, die vom Klick-Ereignishandler der Schaltfläche zum Anheften aufgerufen werden kann. Diese Funktion erfasst mehrere Schritte, die zu der Anheftungsanforderung führen:
- Zuweisen von Eigenschaftswerten, die für die Erstellung der sekundären Kachel erforderlich sind
- Erstellen des Objekts für die sekundäre Kachel
- Angeben zusätzlicher Eigenschaften der sekundären Kachel
- Abrufen der Bildschirmkoordinaten zum Anzeigen des Bestätigungsflyouts (nur Windows)
Einige der Eigenschaften der sekundären Kachel müssen festgelegt werden, bevor sie angeheftet werden kann. Wenn Sie versuchen, eine sekundäre Kachel ohne diese Eigenschaften anzuheften, tritt ein Fehler auf. Die folgenden Eigenschaften sind erforderlich:
- Eine eindeutige ID für die Kachel
- Kurzname (nur Windows 8.0)
- Anzeigename
- Eine Argumentzeichenfolge, die an die übergeordnete Anwendung übergeben wird, wenn die sekundäre Kachel aktiviert wird
- Ein Logobild
- Kacheloptionen (nur Windows 8.0)
In diesem Beispiel wird die Zeit, zu der die sekundäre Kachel an die Startseite angeheftet wurde, als Argumentzeichenfolge übergeben.
Hinweis Unter Windows Phone 8.1 wird der Anzeigename bei einer mittelgroßen sekundären Kachel (150 x 150) nie angezeigt. Außerdem werden alle Telefonkacheln anfänglich als mittelgroße Kacheln angeheftet, sodass der newTileDesiredSize-Parameter am Telefon ignoriert wird.
Hinweis Wenn Sie die ID einer vorhandenen sekundären Kachel angeben, wird die vorhandene sekundäre Kachel überschrieben.
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;
Als Nächstes wird das Objekt für die sekundäre Kachel erstellt. Mit dieser Version des Konstruktors wird eine mittelgroße Kachel erstellt. Wenn Ihre sekundäre Kachel Benachrichtigungen empfängt, wird empfohlen, alle Kachelgrößen zu deklarieren. Dazu stellen Sie mit der SecondaryTileVisualElements-Klasse Logobilder bereit.
var tile = new Windows.UI.StartScreen.SecondaryTile(appbarTileId,
newTileDisplayName,
TileActivationArguments,
square150x150Logo,
newTileDesiredSize);
Da Sie nun über ein Objekt für die sekundäre Kachel verfügen, können Sie Eigenschaften der sekundären Kachel angeben, die nicht über den Konstruktor festgelegt werden. In diesem Beispiel werden die Vordergrundtextfarbe und das kleine Logo angegeben. Außerdem wird festgelegt, dass der Anzeigename auf der Kachel angezeigt wird.
Hinweis Unter Windows Phone 8.1 wird weder das kleine Logo noch der Anzeigename auf einer mittelgroßen sekundären Kachel (150 x 150) angezeigt. Außerdem kann die Vordergrundtextfarbe nicht festgelegt werden. Daher werden diese Eigenschaften, wie sie in diesem Beispiel festgelegt werden, am Telefon ignoriert.
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");
Unter Windows muss der Benutzer den Vorgang bestätigen, damit eine sekundäre Kachel angeheftet werden kann. Im Bestätigungsdialogfeld kann der Benutzer den Anzeigenamen der Kachel überschreiben und aus verschiedenen Kachelgrößen zum Anheften wählen. Das Bestätigungsflyout sollte in der Nähe der Schaltfläche angezeigt werden, über die die Anheftungsanforderung aufgerufen wurde. Bei diesem Beispiel wird das umgebende Rechteck der Schaltfläche zum Anheften abgerufen und festgelegt, dass das Bestätigungsdialogfeld über der Schaltfläche angezeigt werden soll.
Hinweis Unter Windows Phone 8.1 wird dem Benutzer kein Bestätigungsdialogfeld angezeigt. Die Kachel wird auf der Startseite einfach als mittelgroße Kachel ohne Anzeigename angeheftet. Der hier gezeigte Code würde dabei ignoriert werden.
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;
Als Nächstes fordert die Funktion an, dass die sekundäre Kachel angeheftet wird.
- Unter Windows Phone 8.1 wird durch diesen Aufruf die Kachel angeheftet, die App unterbrochen und der Benutzer zur Startseite umgeleitet.
- Unter Windows wird durch diesen Aufruf das Bestätigungsflyout angezeigt, in dem der Benutzer um die Erlaubnis zum Anheften der Kachel gebeten wird. In diesem Beispiel wird das Bestätigungsflyout mithilfe des umgebenden Rechtecks der Schaltfläche zum Anheften oberhalb dieser Koordinaten angezeigt. Erteilt der Benutzer seine Zustimmung, erstellt Windows die sekundäre Kachel und platziert sie auf der Startseite. Der Benutzer bleibt in der App.
return new WinJS.Promise(function (complete, error, progress) {
tile.requestCreateForSelectionAsync(buttonCoordinates, placement).done(function (isCreated) {
if (isCreated) {
complete(true);
} else {
complete(false);
}
});
});
Hinweis Unter Windows Phone 8.1 wird durch einen Aufruf von RequestCreateAsync oder RequestCreateForSelectionAsync die App beendet und der Benutzer zur Startseite umgeleitet. Daher wird kein Code ausgeführt, der auf den RequestCreateAsync- oder RequestCreateForSelectionAsync-Aufruf folgt. Sie sollten also bei Windows Phone 8.1-Projekten auf das Suspending-Ereignis lauschen, damit Sie Aktionen ausführen können (z. B. Speichern des App-Zustands), die vor dem Beenden der App ausgeführt werden müssen.
Die vollständigen appbarButtonClicked- und pinByElementAsync-Funktionen aus dem Beispiel für sekundäre Kacheln werden hier gezeigt.
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. Erstellen einer Funkion zum Lösen
Wenn die sekundäre Kachel bereits angeheftet ist, wird die Schaltfläche zum Anheften zu einer Schaltfläche zum Lösen, und der Klick-Ereignishandler der Schaltfläche löst die Kachel. In diesem Beispiel wird die Funktion bereitgestellt, die der Handler zum Lösen der Kachel aufruft. Wie auch Parameter akzeptiert die Funktion das Objekt für die Schaltfläche zum Anheften. Dies erfolgt wiederum zum Platzieren des Bestätigungsflyouts und der eindeutigen ID der sekundären Kachel. Wie es auch bei der Funktion zum Anheften der Fall ist, wird vom Aufruf zum Lösen ein Promise-Objekt zurückgegeben.
Hinweis Das Lösen von sekundären Kacheln kann auch über die App-Leiste auf der Startseite vorgenommen werden. Sie können ausschließlich diese Methode zum Lösen verwenden. In diesem Fall müssen Sie keine Funktion zum Lösen implementieren oder eine Schaltfläche zum Lösen bereitstellen.
Hinweis Unter Windows Phone 8.1 wird der Benutzer nicht aufgefordert, das Lösen einer sekundären Kachel zu bestätigen. Das Lösen einer sekundären Kachel am Telefon findet genauso statt wie das Lösen jeder anderen Kachel. Der hier gezeigte Code würde dabei ignoriert werden.
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. Implementieren des Ereignishandlers für die Schaltfläche
Wenn der Benutzer auf der App-Leiste auf die Schaltfläche klickt, erscheint ein Flyout mit einer Bestätigungsaufforderung. Um sicherzustellen, dass die App-Leiste nicht geschlossen wird, während das Flyout angezeigt wird, müssen Sie die WinJS.UI.sticky-Eigenschaft der App-Leiste festlegen. Vergewissern Sie sich außerdem, dass das übergeordnete Element des Flyouts richtig zugewiesen ist. In diesem Beispiel werden die setAppbarButton-, die pinByElementAsync- und die unpinByElementAsync-Funktion aufgerufen, die wir in den vorherigen Schritten definiert haben.
Wie Sie sehen ruft der Handler sowohl bei erfolgreichen als auch bei fehlgeschlagenen Anheft- bzw. Lösevorgängen setAppbarButton auf. War der Vorgang erfolgreich, ändert sich die Schaltfläche zum Anheften in die Schaltfläche zum Lösen (oder umgekehrt). Bei einem fehlgeschlagenen Vorgang bleibt die Schaltfläche unverändert. In beiden Fällen muss die Funktion aufgerufen werden, um die WinJS.UI.sticky-Eigenschaft auf false zurückzusetzen, damit die App-Leiste geschlossen werden kann.
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();
}
});
}
}
Zusammenfassung und nächste Schritte
In dieser Schnellstartanleitung haben Sie eine App-Leistenschaltfläche definiert, mit der Benutzer eine sekundäre Kachel anheften bzw. lösen können. Sie haben die sekundäre Kachel erstellt, viele ihrer Eigenschaften festgelegt und das Bestätigungsdialogfeld für den Benutzer angezeigt, durch das das Anheften der sekundären Kachel an die Startseite veranlasst wird.
Nachdem eine sekundäre Kachel angeheftet wurde, erstellt die übergeordnete App-Kachel einen Kanal-URI (Uniform Resource Identifier), damit sie mit der sekundären Kachel kommunizieren kann. Weitere Informationen finden Sie unter Schnellstart: Senden von Benachrichtigungen an eine sekundäre Kachel.
Verwandte Themen
Beispiel für sekundäre Kacheln
Übersicht über sekundäre Kacheln
Schnellstart: Senden von Benachrichtigungen an eine sekundäre Kachel