クイックスタート: WinJS コントロールとスタイルの追加 (HTML)

[アーティクル]
03/04/2016

[ この記事は、Windows ランタイムアプリを作成する Windows 8.x および Windows Phone 8.x 開発者を対象としています。Windows 10 向けの開発を行っている場合は、「最新のドキュメント」をご覧ください]

JavaScript 用 Windows ライブラリ (WinJS) には、高品質なインフラストラクチャ (ページコントロール、promise、データバインドなど)、洗練された UI 機能 (仮想化コレクションなど)、高パフォーマンスな Windows コントロール (ListView、FlipView、SemanticZoom など) が用意されています。

WinJS は、Windows ランタイムアプリや Web サイトで使用できるだけでなく、Apache Cordova などの HTML ベースのアプリテクノロジとも併用できます。

この機能の実際の使い方については「アプリの機能の概要」シリーズの「Windows ストアアプリ UI の概要」をご覧ください。

必要条件

WinJS のテンプレートが使われた JavaScript を使った基本的な Windows ストアアプリの作成経験が必要です。初めてのアプリ作成の説明については、「JavaScript を使った初めての Windows ストアアプリの作成」をご覧ください。
JavaScript を使った Windows ストアアプリでのイベントの処理方法を理解していることを前提とします。イベントを処理するお勧めの方法については、「クイックスタート: HTML コントロールの追加とイベントの処理」をご覧ください。

JavaScript 用 Windows ライブラリとは

WinJS は、CSS ファイルと JavaScript ファイルのライブラリです。JavaScript を使って魅力ある外観のアプリを簡単に開発できるように、名前空間別に体系化された JavaScript オブジェクトが用意されています。 WinJS には、アクティブ化処理、ストレージへのアクセス、独自のクラスと名前空間の定義に使うことができるオブジェクトがあります。

WinJS で提供されるコントロールの一覧については、「コントロールの一覧」をご覧ください。
WinJS には、CSS のスタイルとクラスを使う方法でスタイルを指定する機能も用意されています。これらのスタイルとクラスをそのまま使うことも上書きすることもできます (コントロールのスタイル指定については、「クイックスタート: コントロールのスタイル」をご覧ください)。

ページへの JavaScript 用 Windows ライブラリの追加

アプリまたは Web サイトで最新バージョンの WinJS を使用するには、以下の手順を行います。

[WinJS を入手する] から最新バージョンをダウンロードし、アプリまたは Web サイトのディレクトリにコピーします。
WinJS 機能を使うアプリまたは Web サイトの各ページに WinJS CSS とスクリプト参照を追加します。

この例は、ルートディレクトリに WinJS ファイルがあるアプリでこれらの参照がどのように見えるかを示しています。

    <!-- 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>

マークアップへの WinJS コントロールの追加

HTML コントロールには専用のマークアップ要素がありますが、WinJS にはありません。たとえば、<rating /> 要素を追加しても、Rating コントロールを作成することはできません。WinJS コントロールを追加するには、div 要素を作成し、data-win-control 属性を使ってコントロールの種類を指定します。Rating コントロールを追加するには、この属性を "WinJS.UI.Rating" に設定します。

また、JavaScript コード内で WinJS.UI.processAll 関数を呼び出す必要もあります。WinJS.UI.processAll はマークアップを解析し、検出された WinJS のコントロールをインスタンス化します。

次に示す一連の例では、"空のアプリケーション" テンプレートを使って作成されたプロジェクトに WinJS のコントロールを追加する方法を示します。新しいアプリケーションプロジェクトを作成する場合は、簡単に理解できます。

Hh465493.wedge(ja-jp,WIN.10).gif "新しいアプリケーション" テンプレートを使って新しいプロジェクトを作成するには

Microsoft Visual Studio を起動します。
[スタートページ] タブで、[新しいプロジェクト] をクリックします。[新しいプロジェクト] ダイアログボックスが表示されます。
[インストール済み] ウィンドウで、[JavaScript] を展開し、テンプレートの種類として [Windows ストアアプリ] を選びます。JavaScript で使うことができるプロジェクトテンプレートがダイアログボックスの中央のウィンドウに表示されます。
中央のウィンドウで、[新しいアプリケーション] プロジェクトテンプレートを選びます。
[名前] ボックスに、プロジェクトの名前を入力します。
[OK] をクリックしてプロジェクトを作ります。この処理にはしばらく時間がかかります。

Hh465493.wedge(ja-jp,WIN.10).gif WinJS コントロールを追加するには

コントロールを配置する位置に div 要素を作成します。この要素の data-win-control 属性を、作成するコントロールの完全修飾名に設定します。この例では、アプリのスタートページ (default.html ファイル) 上に Rating コントロールを作成します。

<!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>

JavaScript コードで WinJS.UI.processAll を呼び出し、前の手順で作成した Rating コントロールをインスタンス化する必要があります。 "新しいアプリケーション" テンプレートを使うと、default.js ファイルには既に 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();
})();
```
"新しいアプリケーション" テンプレートを使わない場合または自分で作成したページにコントロールを追加する場合は、WinJS.UI.processAll への呼び出しを追加する必要があります。
- コントロールをアプリのホームページ (通常は default.html ファイル) へ追加した場合、前の例のように、onactivated イベントハンドラー内に WinJS.UI.processAll への呼び出しを追加します。
- コントロールを Page コントロールに追加した場合、WinJS.UI.processAll は、Page コントロールで自動的に呼び出されるので、呼び出す必要はありません。
- アプリのホームページ以外のページにコントロールを追加した場合、DOMContentLoaded イベントを処理し、ハンドラーを使って WinJS.UI.processAll を呼び出します。
```
function initialize() {
    WinJS.UI.processAll();
}

document.addEventListener("DOMContentLoaded", initialize(), false);
```
WinJS.UI.processAll 関数がドキュメントを処理し、マークアップ内で宣言されている WinJS のコントロールをアクティブ化します。

アプリを実行すると、div ホスト要素を配置した場所に Rating コントロールが表示されます。

評価コントロール

マークアップ内での WinJS コントロールプロパティの設定

HTML コントロールを作成する場合、専用の属性を使ってプロパティを設定できます。たとえば、input コントロールの type、min、max の各プロパティを設定するには、マークアップ内で type、min、max の各属性を設定します。

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

HTML コントロールには専用の要素タグと属性タグがありますが、WinJS にはありません。たとえば、マークアップを使って Rating コントロールを作成し、そのプロパティを設定することはできません。

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

マークアップでは、代わりに data-win-options 属性を使ってプロパティを設定します。この属性には、プロパティと値のペアを 1 つ以上指定します。

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

この例では、Rating コントロールの maxRating を 10 に設定します。

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

アプリを実行すると、Rating コントロールは次のように表示されます。

10 個の星で構成される評価システムが表示された Rating コントロール。

複数のプロパティを設定するには、プロパティをコンマで区切ります。

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

次の例では、Rating コントロールの 2 つのプロパティを設定します。

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

アプリを実行すると、Rating コントロールは次のように表示されます。

10 個の星のうち 6 個の評価が表示された Rating コントロール。

プロパティ値が文字列の場合は、data-win-options 属性の設定で使っている引用符と異なる種類の引用符で囲みます。TimePicker コントロールの current プロパティを設定する方法を次の例に示します。このプロパティは文字列を受け取ります。

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

午前 10 時 29 分を示している TimePicker コントロール。

特定の WinJS コントロールでサポートされるプロパティを調べるには、リファレンスページをご覧ください。

マークアップでの作成したコントロールの取得

WinJS のコントロールのプロパティは、プログラムを使って設定することもできます。コード内でコントロールにアクセスするには、ホスト要素を取得し、その winControl プロパティを使ってコントロールを取得します。前に示した例では、Rating コントロールのホスト要素は "ratingControlHost" です。


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

コントロールの取得と操作をできる限り早く実行することが必要な場合もあります。この場合、WinJS.UI.processAll メソッドが非同期メソッドである点に注意してください。WinJS.UI.processAll が完了する前に次のコードが実行されることもあります。コントロールに直ちにアクセスできない場合もあるので、コントロールを直後で操作しないでください。


WinJS.UI.processAll();

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

WinJS.UI.processAll は WinJS.Promise オブジェクトを返します。このオブジェクトを使って、WinJS.UI.processAll が完了したときに関数を呼び出すことができます。コントロールを取得し、その averageRating を 3 に設定する完了関数を定義する例を次に示します。


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

次のセクションでは、イベントリスナーを WinJS のコントロールに追加する方法について説明します。

WinJS コントロールのイベント処理

HTML と同じように、WinJS のコントロールに対してイベントリスナーをアタッチする場合は、addEventListener 関数を使うことをお勧めします。ただし、WinJS のコントロールの取得方法と HTML コントロールの取得方法は少し異なります。

イベントを処理するには:

JavaScript でコントロールのホスト要素を取得し、その winControl プロパティを使ってコントロールを取得します。
コントロールの addEventListener 関数を呼び出し、イベントとイベントハンドラーを指定します。

Rating コントロールの change イベントを処理する方法を次の例に示します。

Hh465493.wedge(ja-jp,WIN.10).gif 評価コントロールの change イベントを処理するには

HTML ファイルに段落を 1 つ追加し、"outputParagraph" という ID を付けます。イベントリスナーの出力は、この段落に表示されます。

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

JavaScript で、ratingChanged という名前のイベントハンドラー関数を作成します。この関数のパラメーターは 1 つです。次の例では、イベントオブジェクトに格納されているプロパティと値を表示するイベントハンドラーを作成します。


    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>";

    }

winControl プロパティを使ってホスト要素からコントロールを取得し、addEventListener を呼び出してイベントハンドラーを追加します。この例では、作成した直後にコントロールを取得し、イベントハンドラーを追加します。

    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); 
            }));
        }
    };

アプリを実行し、評価を変更すると、イベント情報のプロパティと値の一覧が作成されます。

change イベントからの出力。

コードへの WinJS コントロールの追加

ここまでに示した例では、WinJS のコントロールをマークアップ内で作成する方法と操作する方法について説明しましたが、JavaScript コードを代わりに使って WinJS のコントロールを作成することもできます。

Hh465493.wedge(ja-jp,WIN.10).gif WinJS コントロールをコードに追加するには

マークアップ内に、コントロールをホストする要素を作成します。
```
<div id="hostElement"></div>
```
コード内 (DOMContentLoaded イベントハンドラー内をお勧めします) で、ホスト要素を取得します。
```
var hostElement = document.getElementById("hostElement");
```
コントロールのコンストラクターを呼び出し、ホスト要素をコンストラクターに渡して、コントロールを作成します。この例では、Rating コントロールを作成しています。
```
var ratingControl = new WinJS.UI.Rating(hostElement); 
```
プログラムを実行すると、作成した Rating が表示されます。

WinJS.UI.processAll を呼び出す必要はありません。WinJS.UI.processAll を呼び出す必要があるのは、マークアップで WinJS のコントロールを作成するときだけです。

要約と次のステップ

WinJS のコントロールを作成する方法、そのプロパティを設定する方法、イベントハンドラーをアタッチする方法について説明しました。

次のトピックの「クイックスタート: コントロールのスタイル」では、カスケードスタイルシート (CSS) の使い方と、JavaScript を使った Windows ストアアプリのスタイル指定の拡張機能について説明します。特定のコントロールについて詳しくは、「コントロールの一覧」と「機能別コントロール」をご覧ください。

サンプル

ほぼすべての WinJS コントロールとオンラインエディターの実際のコード例については、try.buildwinjs.com をご覧ください。

クイックスタート: WinJS コントロールとスタイルの追加 (HTML)

必要条件

JavaScript 用 Windows ライブラリとは

ページへの JavaScript 用 Windows ライブラリの追加

マークアップへの WinJS コントロールの追加

マークアップ内での WinJS コントロールプロパティの設定

マークアップでの作成したコントロールの取得

WinJS コントロールのイベント処理

コードへの WinJS コントロールの追加

要約と次のステップ

サンプル

関連トピック

その他のリソース

クイック スタート: WinJS コントロールとスタイルの追加 (HTML)

必要条件

JavaScript 用 Windows ライブラリとは

ページへの JavaScript 用 Windows ライブラリの追加

マークアップへの WinJS コントロールの追加

マークアップ内での WinJS コントロール プロパティの設定

マークアップでの作成したコントロールの取得

WinJS コントロールのイベント処理

コードへの WinJS コントロールの追加

要約と次のステップ

サンプル

関連トピック

その他のリソース

クイックスタート: WinJS コントロールとスタイルの追加 (HTML)

マークアップ内での WinJS コントロールプロパティの設定