Language: HTML | XAML

Schnellstart: Anheften einer sekundären Kachel (XAML)

Applies to Windows and Windows Phone

Hinweis  Sie verwenden nicht C#/VB/C++? Weitere Informationen finden Sie unter Schnellstart: Anheften einer sekundären Kachel (HTML).

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

Damit Sie die folgenden Ausführungen verstehen, benötigen Sie Folgendes:

  • Grundkenntnisse der Begriffe und Konzepte für sekundäre Kacheln. Weitere Informationen finden Sie unter Übersicht über sekundäre Kacheln.
  • Sie können eine einfache Windows Store-App mit C# oder C++ mit Windows-Runtime-APIs erstellen. Weitere Informationen finden Sie unter Erstellen Ihrer ersten Windows Store-App mit C# oder Visual Basic.
  • Grundkenntnisse zum Erstellen von CodeBehind für eine Extensible Application Markup Language-(XAML-)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. Optional: Hinzufügen von Namespaces

Um Ihren Code zu vereinfachen, fügen Sie die folgenden Zeilen der CS-Dateien in Ihrem Projekt hinzu, die den Code (bzw. Ihre Version davon) enthalten, der im Rest dieser Schnellstartanleitung gezeigt wird. Beim gesamten Code in diesem Thema wird vorausgesetzt, dass Sie diese Zeilen hinzugefügt haben. Andernfalls wird er nicht unverändert kompiliert. Windows.UI.StartScreen enthält die Objekte der sekundären Kachel, und Windows.UI.Xaml.Controls wird mit App-Leisten und Schaltflächen verwendet.



using Windows.UI.StartScreen;
using Windows.UI.Xaml.Controls;

2. 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.

  • Applies to Windows Phone

Unter Windows Phone geschieht das Anheften normalerweise über ein Kontextmenü und nicht über eine Schaltfläche auf einer App-Leiste.

Wenn der Benutzer unter Windows die Schaltfläche zum Anheften/Lösen auswählt, erscheint ein Flyout mit einer Bestätigungsaufforderung. Setzen Sie die IsSticky-Eigenschaft auf True, damit die App-Leiste nicht geschlossen wird, während das Flyout angezeigt wird.

Dieser Code wird der XAML-Seite in Ihrem Projekt hinzugefügt, für die der restliche Code in diesem Thema der CodeBehind ist.



<Page.BottomAppBar>
    <CommandBar x:Name="SecondaryTileCommandBar" Padding="10,0,10,0" IsSticky="True" IsOpen="True">
        <AppBarButton x:Name="PinUnPinCommandButton" Icon="Pin" Label="Pin" />
    </CommandBar>
</Page.BottomAppBar>

3. Bereitstellen einer eindeutigen ID für Ihre sekundäre Kachel



public const string appbarTileId = "MySecondaryTile";

4. 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.



private void ToggleAppBarButton(bool showPinButton)
{
    if (showPinButton)
    {
        this.PinUnPinCommandButton.Label = "Pin to Start";
        this.PinUnPinCommandButton.Icon = new SymbolIcon(Symbol.Pin);
    }
    else
    {
        this.PinUnPinCommandButton.Label = "Unpin from Start";
        this.PinUnPinCommandButton.Icon = new SymbolIcon(Symbol.UnPin);
    }

    this.PinUnPinCommandButton.UpdateLayout();
}

5. 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 ToggleAppBarButton-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 pinToAppBar_Click 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.



void Init()
{
    ToggleAppBarButton(!SecondaryTile.Exists(MainPage.appbarTileId));
    this.PinUnPinCommandButton.Click += this.pinToAppBar_Click;
}

6. 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.

  • Applies to Windows Phone

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.



string displayName = "Secondary tile pinned through app bar";
string tileActivationArguments = MainPage.appbarTileId + " was pinned at=" + DateTime.Now.ToLocalTime().ToString();
Uri square150x150Logo = new Windows.Foundation.Uri("ms-appx:///Assets/square150x150Tile-sdk.png");
TileSize newTileDesiredSize = 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.



SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId, 
                                                displayName, 
                                                tileActivationArguments,
                                                square150x150Logo, 
                                                TileSize.Square150x150);

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.

  • Applies to Windows Phone

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.



secondaryTile.VisualElements.ShowNameOnSquare150x150Logo = true;                       
secondaryTile.VisualElements.ForegroundText = ForegroundText.Dark;                        
secondaryTile.VisualElements.Square30x30Logo = new 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 ("Sender") abgerufen und festgelegt, dass das Bestätigungsdialogfeld über der Schaltfläche angezeigt werden soll.

  • Applies to Windows Phone

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.



Windows.Foundation.Rect rect = MainPage.GetElementRect((FrameworkElement)sender);
Windows.UI.Popups.Placement 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.


bool isPinned = await secondaryTile.RequestCreateForSelectionAsync(rect, placement);

  • Applies to Windows Phone

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.

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 der Code bereitgestellt, den der Handler zum Lösen der Kachel asynchron aufruft. Wie bereits erwähnt, wird die Kachel durch diesen Aufruf nicht wirklich von der Startseite gelöst. Stattdessen wird ein Bestätigungsdialogfeld angezeigt. Erteilt der Benutzer seine Zustimmung, entfernt Windows die sekundäre Kachel von der Startseite.

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.



SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId);
bool isUnpinned = await secondaryTile.RequestDeleteForSelectionAsync(rect, placement);

Zum Abschluss wird die IsSticky-Eigenschaft der App-Leiste auf false zurückgesetzt, damit das Flyout geschlossen werden kann.



rootPage.BottomAppBar.IsSticky = false;

Der vollständige pinToAppBar_Click-Ereignishandler ist hier dargestellt. Wie Sie sehen ruft der Handler sowohl nach Anheft- als auch nach Lösevorgängen ToggleAppBarButton auf. Wenn der Vorgang fehlschlägt, wird die Schaltfläche nicht umgeschaltet.



async void pinToAppBar_Click(object sender, RoutedEventArgs e)
{
#if WINDOWS_APP
    this.SecondaryTileCommandBar.IsSticky = true;
#endif
    
    if (SecondaryTile.Exists(MainPage.appbarTileId))
    {
        // Unpin
        SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId);
    
        Windows.Foundation.Rect rect = MainPage.GetElementRect((FrameworkElement)sender);
        Windows.UI.Popups.Placement placement = Windows.UI.Popups.Placement.Above;
        
        bool isUnpinned = await secondaryTile.RequestDeleteForSelectionAsync(rect, placement);
    
        ToggleAppBarButton(isUnpinned);
    }
    else
    {
        // Pin
        Uri square150x150Logo = new Uri("ms-appx:///Assets/square150x150Tile-sdk.png");
        string tileActivationArguments = MainPage.appbarTileId + " was pinned at = " + DateTime.Now.ToLocalTime().ToString();
        string displayName = "Secondary tile pinned through app bar";
    
        TileSize newTileDesiredSize = TileSize.Square150x150;
    
        SecondaryTile secondaryTile = new SecondaryTile(MainPage.appbarTileId,
                                                        displayName, 
                                                        tileActivationArguments,
                                                        square150x150Logo,
                                                        newTileDesiredSize);
    
        Uri square30x30Logo = new Uri("ms-appx:///images/square30x30Tile-sdk.png");
        secondaryTile.VisualElements.Square30x30Logo = new Uri("ms-appx:///images/square30x30Tile-sdk.png");
        secondaryTile.VisualElements.ShowNameOnSquare150x150Logo = true;
        secondaryTile.VisualElements.ForegroundText = ForegroundText.Dark;
    
        Windows.Foundation.Rect rect = MainPage.GetElementRect((FrameworkElement)sender);
        Windows.UI.Popups.Placement placement = Windows.UI.Popups.Placement.Above;

#if WINDOWS_APP
        bool isPinned = await secondaryTile.RequestCreateForSelectionAsync(rect, placement);

        ToggleAppBarButton(!isPinned);
#endif

#if WINDOWS_PHONE_APP
       await secondaryTile.RequestCreateAsync();
#endif
    }

#if WINDOWS_APP
    this.BottomAppBar.IsSticky = false;
#endif
}

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
Richtlinien und Prüfliste für sekundäre Kacheln
SecondaryTile class

 

 

Anzeigen:
© 2014 Microsoft