クイックスタート: セカンダリタイルのピン留め (HTML)

[アーティクル]
12/22/2015

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

注 JavaScript を使わない場合は、「クイックスタート: セカンダリタイルのピン留め (XAML)」をご覧ください。

このトピックでは、アプリのセカンダリタイルを作り、スタート画面にピン留めする手順について説明します。

必要条件

このトピックを理解するための要件:

セカンダリタイルに関する用語と概念についての実用的知識。詳しくは、「セカンダリタイルの概要」をご覧ください。
Windows ランタイム API を使って JavaScript で基本的な Windows ストアアプリを作成できること。詳しくは、「JavaScript を使った初めての Windows ストアアプリの作成」をご覧ください。
Microsoft Visual Basic を使って HTML ベースの Windows ストアアプリのコードを作る方法を理解していること。

重要このトピックで紹介するコードを完全なサンプルで確認するには、セカンダリタイルのサンプルをご覧ください。このサンプルには、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. セカンダリタイルの一意の ID を指定する


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 関数を使って、セカンダリタイルが既にピン留めされていて、それに応じてボタンテキストが設定されているかどうかを確認します。

その後、ピン留めボタンの click イベントに appbarButtonClicked ハンドラーを割り当てます。次の手順でイベントハンドラーの実装方法を説明します。

この手順に示すコードは、実行する必要がある他の初期化と共に、アプリが起動されるたびにアプリの初期化の一部として呼び出します。


document.getElementById("pinUnpinFromAppbar").disabled = false;
setAppbarButton();

id("commandButton").addEventListener("click", appbarButtonClicked, false);

5. ボタンのイベントハンドラーでセカンダリタイルを作り、ピン留めする

この例は、ピン留めボタンのクリックイベントハンドラーから呼び出すことのできる単一の関数を実装します。この関数には、ピン留め要求につながるいくつかのステップが組み込まれています。

セカンダリタイルの作成に必要なプロパティ値を割り当てる
セカンダリタイルオブジェクトを作成する
セカンダリタイルの追加のプロパティを指定する
確認ポップアップを表示するための画面座標を取得する (Windows のみ)

セカンダリタイルの一部のプロパティは、セカンダリタイルをピン留めする前に設定する必要があります。これらのプロパティのうちの 1 つ以上を設定せずにセカンダリタイルをピン留めしようとすると、失敗します。必須のプロパティは次のとおりです。

タイルの一意の ID
短い名前 (Windows 8.0 のみ)
表示名
セカンダリタイルがアクティブ化されるときに親アプリケーションに渡される引数文字列
ロゴイメージ
タイルのオプション (Windows 8.0 のみ)

引数文字列の例として、このサンプルはセカンダリタイルがピン留めされた時間をスタート画面に渡しています。

注 Windows Phone 8.1 では、普通サイズ (150x150) のセカンダリタイルには表示名が表示されません。また、すべての電話タイルは最初は普通サイズのタイルとしてピン留めされるため、newTileDesiredSize パラメーターは電話では無視されます。

注既にあるセカンダリタイルの ID と同じ ID を指定した場合、既にあるセカンダリタイルが上書きされます。


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 では、小さいロゴも表示名も普通サイズ (150x150) のセカンダリタイルに表示されず、前景のテキストの色を指定できないため、この例で設定されているプロパティは電話では無視されます。


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 イベントをリッスンして、アプリが終了する前に実行する必要があるすべての操作 (アプリの状態を保存するなど) を実行できるようにする必要があります。

セカンダリタイルのサンプルに含まれている完全な pinByElementAsync 関数と appbarButtonClicked 関数を次に示します。


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. ピン留めを外す関数を作成する

セカンダリタイルが既にピン留めされているときは、ピン留めボタンはピン留めを外すボタンになり、ボタンのクリックイベントハンドラーによってタイルのピン留めが外されます。この例では、タイルのピン留めを外すためにハンドラーが呼び出す関数を紹介します。この関数はパラメーターとしてピン留めボタンオブジェクトを受け取ります。さらに、確認ポップアップを配置する目的で、セカンダリタイルの一意の ID を受け取ります。ピン留め関数と同様、ピン留めを外すための呼び出しも 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();
            }
        });
    }
}

要約と次のステップ

このクイックスタートでは、ユーザーがセカンダリタイルをピン留めしたり、ピン留めを外したりするために使える、アプリバー上のボタンを定義しました。セカンダリタイルを作り、そのプロパティの多くを定義し、確認ダイアログをユーザーに表示しました。その結果、最終的にスタート画面にセカンダリタイルが追加されました。

セカンダリタイルがピン留めされると、親のアプリのタイルによってチャネルの Uniform Resource Identifier (URI) が作られ、親のアプリのタイルがセカンダリタイルと連絡できるようになります。詳しくは、「クイックスタート: 通知をセカンダリタイルに送信」を参照してください。

次の方法で共有

クイックスタート: セカンダリタイルのピン留め (HTML)

必要条件

手順

1. ピン留め/ピン留めを外すボタンを含むアプリバーを追加する

2. セカンダリタイルの一意の ID を指定する

3. ピン留めボタンまたはピン留めを外すボタンとしてボタンを設定する関数を作る

4. 適切なボタンを表示してボタンのクリックハンドラーを割り当てる

5. ボタンのイベントハンドラーでセカンダリタイルを作り、ピン留めする

6. ピン留めを外す関数を作成する

7. ボタンのイベントハンドラーを実装する

要約と次のステップ

関連トピック

その他のリソース

次の方法で共有

クイック スタート: セカンダリ タイルのピン留め (HTML)

必要条件

手順

1. ピン留め/ピン留めを外すボタンを含むアプリ バーを追加する

2. セカンダリ タイルの一意の ID を指定する

3. ピン留めボタンまたはピン留めを外すボタンとしてボタンを設定する関数を作る

4. 適切なボタンを表示してボタンのクリック ハンドラーを割り当てる

5. ボタンのイベント ハンドラーでセカンダリ タイルを作り、ピン留めする

6. ピン留めを外す関数を作成する

7. ボタンのイベント ハンドラーを実装する

要約と次のステップ

関連トピック

その他のリソース

クイックスタート: セカンダリタイルのピン留め (HTML)

1. ピン留め/ピン留めを外すボタンを含むアプリバーを追加する

2. セカンダリタイルの一意の ID を指定する

4. 適切なボタンを表示してボタンのクリックハンドラーを割り当てる

5. ボタンのイベントハンドラーでセカンダリタイルを作り、ピン留めする

7. ボタンのイベントハンドラーを実装する