Schnellstart: Hinzufügen von WinJS-Steuerelementen und -Stilen (HTML)

Artikel
03/04/2016

[ 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 ]

Die Windows-Bibliothek für JavaScript (WinJS) stellt eine hochwertige Infrastruktur (beispielsweise in Form von Seitensteuerelementen, Zusagen und Datenbindungen), optimierte Benutzeroberflächen-Features (wie etwa Virtualisierungssammlungen) sowie leistungsstarke Windows-Steuerelemente wie ListView, FlipView und SemanticZoom bereit.

Sie können WinJS in Ihren Windows-Runtime-Apps, auf Ihren Websites und bei der Verwendung von HTML-basierten App-Technologien wie Apache Cordova verwenden.

Dieses Feature können Sie im Rahmen unserer Reihe App-Features von A bis Z in Aktion erleben: Windows Store-App-UI von A bis Z.

Voraussetzungen

Es wird davon ausgegangen, dass Sie eine einfache Windows Store-App mit JavaScript erstellen können, für die die WinJS-Vorlage verwendet wird. Informationen zum Erstellen der ersten App finden Sie unter Erstellen Ihrer ersten Windows Store-App mit JavaScript.
Es wird davon ausgegangen, dass Sie mit dem Behandeln von Ereignissen in einer Windows Store-App mit JavaScript vertraut sind. Informationen zur empfohlenen Methode zum Behandeln von Ereignissen finden Sie unter Schnellstart: Hinzufügen von HTML-Steuerelementen und Behandeln von Ereignissen.

Was ist die Windows-Bibliothek für JavaScript?

WinJS ist eine Bibliothek mit CSS- und JavaScript-Dateien. Sie enthält JavaScript-Objekte, die in Namespaces organisiert sind und das Entwickeln von ansprechenden Apps vereinfachen sollen. WinJS enthält Objekte für das Behandeln der Aktivierung, den Zugriff auf den Speicher und das Definieren eigener Klassen und Namespaces.

Eine vollständige Liste der in WinJS bereitgestellten Steuerelemente finden Sie in der Liste der Steuerelemente.
WinJS bietet darüber hinaus auch Formatierungsfeatures in Form von CSS-Stilen und -Klassen, die Sie verwenden oder überschreiben können. (Das Formatieren von Steuerelementen wird in Schnellstart: Formatieren von Steuerelementen beschrieben.)

Hinzufügen der Windows-Bibliothek für JavaScript zu Ihrer Seite

So verwenden Sie die neueste Version von WinJS in Ihrer App oder Website:

Laden Sie die aktuelle Version unter WinJS herunterladen herunter, und kopieren Sie sie in das Verzeichnis für Ihre App oder Website.
Fügen Sie WinJS-CSS- und Skriptverweise zu allen Seiten Ihrer App oder Website hinzu, die WinJS-Features verwendet.

Dieses Beispiel zeigt, wie diese Verweise für eine App aussehen, die die WinJS-Dateien im Stammverzeichnis enthält.

    <!-- WinJS style sheets (include one) -->
    <link href="/WinJS/css/ui-dark.css" rel="stylesheet">
    <link href="/WinJS/css/ui-light.css" rel="stylesheet">

    <!-- WinJS code -->
    <script src="/WinJS/js/WinJS.js"></script>

Hinzufügen von WinJS-Steuerelementen im Markup

Im Gegensatz zu HTML-Steuerelementen besitzen WinJS-Steuerelemente keine dedizierten Markupelemente: Sie können ein Rating-Steuerelement erstellen, indem Sie z. B. ein <rating />-Element hinzufügen. Zum Hinzufügen eines WinJS-Steuerelements erstellen Sie ein div-Element und geben mit dem data-win-control-Attribut den gewünschten Steuerelementtyp an. Zum Hinzufügen eines Rating-Steuerelements legen Sie das Attribut auf "WinJS.UI.Rating" fest.

Sie müssen auch die WinJS.UI.processAll-Funktion in Ihrem JavaScript-Code aufrufen. WinJS.UI.processAll analysiert Ihr Markup und instanziiert alle gefundenen WinJS-Steuerelemente.

Die folgenden Beispiele veranschaulichen das Hinzufügen eines WinJS-Steuerelements zu einem Projekt, das mit der Vorlage "Leere Anwendung" erstellt wurde. Das Verständnis wird erleichtert, wenn Sie ein neues Projekt mit "Leere Anwendung" erstellen.

Hh465493.wedge(de-de,WIN.10).gif So erstellen Sie ein neues Projekt mit der Vorlage "Leere Anwendung"

Starten Sie Microsoft Visual Studio.
Klicken Sie auf der Registerkarte Startseite auf Neues Projekt. Das Dialogfeld Neues Projekt wird geöffnet.
Erweitern Sie im Bereich Installiert den Eintrag JavaScript, und klicken Sie auf den Vorlagentyp Windows Store-App. Die verfügbaren Projektvorlagen für JavaScript werden im mittleren Bereich des Dialogfelds angezeigt.
Wählen Sie im mittleren Fenster die Projektvorlage Leere Anwendung aus.
Geben Sie im Textfeld Name einen Namen für Ihr Projekt ein.
Klicken Sie auf OK, um das Projekt zu erstellen. Dies wird einen Moment dauern.

Hh465493.wedge(de-de,WIN.10).gif So fügen Sie ein WinJS-Steuerelement hinzu

Erstellen Sie ein div-Element, in dem Sie das Steuerelement platzieren möchten. Legen Sie das data-win-control-Attribut auf den vollqualifizierten Namen des zu erstellenden Steuerelements fest. In diesem Beispiel wird ein Rating-Steuerelement auf der Startseite der App (die Datei default.html) erstellt.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Adding WinJS controls and styles</title>

    <!-- WinJS references -->
    <link href="/WinJS/css/ui-dark.css" rel="stylesheet">
    <script src="/WinJS/js/WinJS.js"></script>

    <!-- AddingWinJSControlsAndStyles references -->
    <link href="/css/default.css" rel="stylesheet">
    <script src="/js/default.js"></script>
</head>
<body>

    <p>Create a WinJS control in markup</p>

    <div id="ratingControlHost" data-win-control="WinJS.UI.Rating">
    </div>

</body>
</html>

Ihr JavaScript-Code muss WinJS.UI.processAll aufrufen, um das im vorherigen Schritt erstellte Rating-Steuerelement zu initialisieren. Wenn Sie die Vorlage Leere Anwendung verwenden, enthält die Datei "default.js" bereits einen Aufruf von WinJS.UI.processAll:

(function () {
    "use strict";

    var app = WinJS.Application;
    var activation = Windows.ApplicationModel.Activation;
    WinJS.strictProcessing();

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                // TODO: This application has been newly launched. Initialize
                // your application here.
            } else {
                // TODO: This application has been reactivated from suspension.
                // Restore application state here.
            }
            args.setPromise(WinJS.UI.processAll());
        }
    };

    app.oncheckpoint = function (args) {
        // TODO: This application is about to be suspended. Save any state
        // that needs to persist across suspensions here. You might use the
        // WinJS.Application.sessionState object, which is automatically
        // saved and restored across suspension. If you need to complete an
        // asynchronous operation before your application is suspended, call
        // args.setPromise().
    };

    app.start();
})();

Wenn Sie nicht die Vorlage "Leere Anwendung" verwenden oder wenn Sie das Steuerelement auf einer Seite hinzufügen, die Sie selbst erstellt haben, müssen Sie möglicherweise noch einen Aufruf von WinJS.UI.processAll hinzufügen.

Wenn Sie das Steuerelement auf der Startseite Ihrer App (i. d. R. die Datei "default.html") hinzugefügt haben, fügen Sie den Aufruf von WinJS.UI.processAll wie im vorherigen Beispiel gezeigt in Ihrem onactivated-Ereignishandler hinzu.
Wenn Sie das Steuerelement einer Seitensteuerung hinzufügen, müssen Sie WinJS.UI.processAll nicht aufrufen, da die Seitensteuerung dies für Sie übernimmt.
Wenn Sie das Steuerelement auf einer anderen Seite als der Startseite hinzugefügt haben, behandeln Sie das DOMContentLoaded-Ereignis, und rufen Sie mit dem Ereignishandler WinJS.UI.processAll auf.
```
function initialize() {
    WinJS.UI.processAll();
}

document.addEventListener("DOMContentLoaded", initialize(), false);
```

Die WinJS.UI.processAll-Funktion verarbeitet das Dokument und aktiviert alle WinJS-Steuerelemente, die Sie im Markup deklariert haben.

Wenn Sie die App ausführen, wird das Rating-Steuerelement an der Stelle angezeigt, an der Sie es im übergeordneten div-Element angeordnet haben.

Ein Bewertungssteuerelement

Festlegen der Eigenschaften eines WinJS-Steuerelements im Markup

Wenn Sie ein HTML-Steuerelement erstellen, können Sie dessen Eigenschaften mit speziellen Attributen festlegen. Wenn Sie z. B. die Eigenschaften type, min und max eines input-Steuerelements festlegen möchten, können Sie im Markup die Attribute type, min und max festlegen:

<input type="range" min="0" max="20" />

Im Gegensatz zu HTML-Steuerelementen besitzen WinJS-Steuerelemente keine dedizierten Elemente oder Attributtags. Sie können also nicht z. B. ein Rating-Steuerelement erstellen und dessen Eigenschaften mit folgendem Markup festlegen:

<!-- Not valid markup. -->
<rating maxRating="10" averageRating="6" />

Verwenden Sie stattdessen das data-win-options-Attribut, um im Markup eine Eigenschaft festzulegen. Dieses übernimmt ein oder mehrere Eigenschaft/Wert-Paare:

data-win-options="{propertyName: propertyValue}"

Dieses Beispiel legt das maxRating eines Rating-Steuerelements auf 10 fest.

<div id="ratingControlHost" data-win-control="WinJS.UI.Rating"
    data-win-options="{maxRating: 10}">
</div>

Wenn Sie die App ausführen, wird das Rating-Steuerelement folgendermaßen dargestellt:

Bewertungssteuerelement mit einer Bewertung von 10 Sternen.

Wenn Sie mehrere Eigenschaften festlegen möchten, trennen Sie diese durch Kommas voneinander ab:

data-win-options="property1Name: property1Value, property2Name: property2Value"

Das folgende Beispiel legt zwei Eigenschaften des Rating-Steuerelements fest.

<div id="ratingControlHost" data-win-control="WinJS.UI.Rating"
    data-win-options="{maxRating: 10, averageRating: 6}">
</div>

Wenn Sie die App ausführen, wird das Rating-Steuerelement nun folgendermaßen dargestellt:

Bewertungssteuerelement mit einer Bewertung von 6 aus 10 Sternen.

Wenn der Eigenschaftenwert eine Zeichenfolge ist, schließen Sie diese in andere Anführungszeichen (' oder ") ein als das data-win-options-Attribut. Dieses Beispiel veranschaulicht das Festlegen der current-Eigenschaft des TimePicker-Steuerelements, das eine Zeichenfolge übernimmt:

<div id="timepicker" data-win-control="WinJS.UI.TimePicker" 
    data-win-options="{current: '10:29 am'}">
</div>

Ein TimePicker-Steuerelement mit der Uhrzeit 10:29 AM.

Wenn Sie ermitteln möchten, ob eine Eigenschaft von einem bestimmten WinJS-Steuerelement unterstützt wird, lesen Sie dessen Referenzseite.

Abrufen eines von Ihnen im Markup erstellten Steuerelements

Sie können die Eigenschaften eines WinJS-Steuerelements auch programmgesteuert festlegen. Rufen Sie für den Zugriff auf das Steuerelement im Code das übergeordnete Element ab, und verwenden Sie dann dessen winControl-Eigenschaft für das Abrufen des Steuerelements. Im vorherigen Beispiel ist "ratingControlHost" das übergeordnete Element des Rating-Steuerelements.


var control = document.getElementById("ratingControlHost").winControl;

In einigen Fällen möchten Sie eventuell das Steuerelement sofort abrufen und ändern, sowie es verfügbar wird. Beachten Sie, dass die WinJS.UI.processAll-Methode asynchron ist, sodass folgender Code möglicherweise ausgeführt wird, bevor WinJS.UI.processAll abgeschlossen wurde. Daher sollten Sie nicht sofort versuchen, das Steuerelement zu ändern, da es nicht verfügbar sein könnte:


WinJS.UI.processAll();

// Don't do this:
var control = document.getElementById("ratingControlHost").winControl; 
control.averageRating = 3;

WinJS.UI.processAll gibt ein WinJS.Promise-Objekt zurück, mit dem Sie nach Abschluss der WinJS.UI.processAll-Methode eine Funktion aufrufen können. Dieses Beispiel definiert eine Abschlussfunktion, die das Steuerelement abruft und dessen averageRating auf 3 festlegt.


// Do this instead:
WinJS.UI.processAll().then(function () {
    var control = document.getElementById("ratingControlHost").winControl;
    control.averageRating = 3; 
});

Im nächsten Abschnitt wird das Hinzufügen von Ereignishandlern zu einem WinJS-Steuerelement beschrieben.

Behandeln von Ereignissen von WinJS-Steuerelementen

Wie bei HTML-Steuerelementen wird für das Anfügen von Ereignishandlern auch bei WinJS-Steuerelementen die Verwendung der addEventListener-Funktion empfohlen. Das Abrufen eines WinJS-Steuerelements unterscheidet sich jedoch etwas vom Abrufen eines HTML-Steuerelements.

So behandeln Sie ein Ereignis

Rufen Sie in JavaScript das übergeordnete Element des Steuerelements ab, und verwenden Sie dessen winControl-Eigenschaft zum Abrufen des Steuerelements.
Rufen Sie die addEventListener-Funktion des Steuerelements auf, und geben Sie ein Ereignis und einen Ereignishandler an.

Das nächste Beispiel veranschaulicht das Behandeln des change-Ereignisses eines Rating-Steuerelements.

Hh465493.wedge(de-de,WIN.10).gif So behandeln Sie das Änderungsereignis eines Bewertungssteuerelements

Fügen Sie in Ihrer HTML-Datei einen Absatz mit der ID "outputParagraph" ein. Die Ausgabe Ihres Ereignishandlers erfolgt in diesen Absatz.

        <p>Create a WinJS control in markup</p>

        <div id="ratingControlHost" data-win-control="WinJS.UI.Rating"
            data-win-options="{maxRating: 10, averageRating: 6}">
        </div>

        <!-- This paragraph will be used to demonstrate event handling. -->
        <p id="outputParagraph"></p>

Erstellen Sie in Ihrem JavaScript-Code eine Ereignishandlerfunktion namens ratingChanged, die einen Parameter übernimmt. Das folgende Beispiel erstellt einen Ereignishandler, der die Eigenschaften und Werte im Ereignisobjekt anzeigt.


    function ratingChanged(event) {

        var outputParagraph = document.getElementById("outputParagraph");
        var output = event.type + ": <ul>";
        var property;
        for (property in event) {
            output += "<li>" + property + ": " + event[property] + "</li>";
        }

        outputParagraph.innerHTML = output + "</ul>";

    }

Rufen Sie mithilfe der winControl-Eigenschaft das Steuerelement aus seinem Hostelement ab, und rufen Sie die addEventListener-Funktion auf, um den Ereignishandler hinzuzufügen. Dieses Beispiel ruft das Steuerelement ab, sowie es erstellt wurde, und fügt den Ereignishandler hinzu:

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                // TODO: This application has been newly launched. Initialize
                // your application here.
            } else {
                // TODO: This application has been reactivated from suspension.
                // Restore application state here.
            }
            args.setPromise(WinJS.UI.processAll().then(function () {
                var control = document.getElementById("ratingControlHost").winControl;
                control.addEventListener("change", ratingChanged, false); 
            }));
        }
    };

Wenn Sie die App ausführen und die Bewertung ändern, wird eine Liste der Eigenschaften und Werte mit den Ereignisinformationen erstellt.

Die Ausgabe des Änderungsereignis.

Hinzufügen von WinJS-Steuerelementen im Code

Die vorherigen Beispiele zeigen, wie Sie ein im Markup erstelltes WinJS-Steuerelement erstellen und ändern. Sie können WinJS-Steuerelemente aber auch mit JavaScript-Code erstellen.

Hh465493.wedge(de-de,WIN.10).gif So erstellen Sie ein WinJS-Steuerelement im Code

Erstellen Sie im Markup das Element, das als übergeordnetes Element für das Steuerelement fungiert.
```
<div id="hostElement"></div>
```
Rufen Sie das übergeordnete Element in Ihrem Code (bevorzugt im DOMContentLoaded-Ereignishandler) ab.
```
var hostElement = document.getElementById("hostElement");
```
Erstellen Sie Ihr Steuerelement, indem Sie seinen Konstruktor aufrufen und das Hostelement an den Konstruktor übergeben. In diesem Beispiel wird ein Rating-Steuerelement erstellt:
```
var ratingControl = new WinJS.UI.Rating(hostElement); 
```
Wenn Sie das Programm ausführen, wird das erstellte Rating angezeigt:

Sie müssen WinJS.UI.processAll nicht aufrufen. Sie müssen WinJS.UI.processAll nur aufrufen, wenn Sie ein WinJS-Steuerelement im Markup erstellen.

Zusammenfassung und nächste Schritte

Sie haben erfahren, wie Sie WinJS-Steuerelemente erstellen, wie Sie deren Eigenschaften festlegen und wie Sie Ereignishandler anfügen.

Im nächsten Thema, Schnellstart: Formatieren von Steuerelementen, werden die Verwendung von CSS (Cascading Stylesheets) sowie die verbesserten Formatierungsmöglichkeiten von Windows Store-Apps mit JavaScript erläutert. Weitere Informationen zu einzelnen Steuerelementen finden Sie in der Steuerelementliste und unter Steuerelemente nach Funktion.

Beispiele

Live-Codebeispiele zu fast allen WinJS-Steuerelement und einen Online-Editor finden Sie unter try.buildwinjs.com.