クイック スタート: 共有コンテンツの受信 (HTML)

  • [アーティクル]

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

このクイックスタートでは、別のアプリから共有コンテンツを受け取る手順について説明します。

目標: 共有コンテンツを受け取る方法について理解する。

必要条件

このセクションで説明するコードを使うには、次の条件を満たしている必要があります。

  • Visual Studio と関連するテンプレートについて理解している必要があります。
  • JavaScript について理解している必要があります。

手順

1. 共有コントラクトをサポートする。

アプリで共有コンテンツを受け取るには、事前に共有コントラクトのサポートを宣言する必要があります。このコントラクトを使うと、アプリがコンテンツを受け取れることをシステムに通知できます。Visual Studio テンプレートを使ってアプリを作る場合は、次の手順に従って共有コントラクトをサポートします。

  1. マニフェスト ファイルを開きます。マニフェスト ファイルの名前は package.appxmanifest です。
  2. [宣言] タブを開きます。
  3. [使用可能な宣言] ボックスの一覧の [共有ターゲット] を選びます。

詳しくは、「共有ターゲット コントラクト項目テンプレート」をご覧ください。

2. サポートするファイルの種類とデータ形式の指定

ターゲット アプリの開発者は、サポートするファイルの種類とデータ形式を決定する必要があります。サポートするファイルの種類を指定するには、次の操作を実行します。

  1. マニフェスト ファイルを開きます。
  2. [宣言] ページの [サポートされるファイルの種類] セクションで、[新規追加] をクリックします。
  3. サポートするファイル名拡張子を入力します。たとえば、「.docx」と入力します。ピリオド (.) を忘れないように注意してください。

すべてのファイルの種類をサポートする場合は、SupportsAnyFileType ボックスをオンにします。

サポートするデータ形式を指定するには、次の操作を実行します。

  1. マニフェスト ファイルを開きます。
  2. [データ形式] セクションで、[新規追加] をクリックします。
  3. サポートするデータ形式の名前を入力します。たとえば、"テキスト" と入力します。

共有 API では、テキスト、HTML、ビットマップなど複数の標準形式がサポートされます。カスタムのファイルの種類とデータ形式を指定することもできます。その場合は、それらの種類と形式がどのようなものかをソース アプリが把握している必要があります。そうでないと、アプリはその種類のデータを共有できません。

3. 共有のアクティブ化の処理

ユーザーがアプリを選ぶと、アプリケーションの activated イベントが発生します。アプリはこのイベントを処理して、ユーザーが共有するデータを処理する必要があります。activated イベントが発生する理由はさまざまです。そのため、最初に行う必要があるのは、イベントの理由がデータの共有なのかどうかを調べることです。

if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
    // Code to handle activation goes here.
}

ユーザーが共有するデータは、ShareOperation オブジェクトに格納されています。このオブジェクトを使うと、オブジェクトに格納されているデータの形式を調べることができます。テキスト形式の共有コンテンツを処理するイベント ハンドラーを次に示します。

var shareOperation = eventObject.detail.shareOperation;
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
    shareOperation.data.getTextAsync().done(function (text) {
            // To output the text using this example, 
            // you need a div tag with an id of "output" in your HTML file.
            document.getElementById("output").innerText = text;
        }, function (e) {
            displayError("Error retrieving Text format: " + e);
        }
    });
}

4. 長時間共有状態の報告 (時間のかかる操作の場合)

注  

次の手順は Windows ストア アプリにのみ適用されます。ここで使っている報告用のメソッドは Windows Phone 8.1 からも呼び出すことができますが、その場合はデータは返されません。

場合によっては、ユーザーが共有するデータをアプリが処理するのに時間がかかることがあります。このような共有インスタンスを長時間共有と呼びます。長時間共有の例として、ファイルまたは画像のコレクションの共有があります。これらの項目は単純なテキスト文字列より大きいため、処理に時間がかかります。

注  アプリがテキストやハイパーリンクなどの単純なものしか受け取れない場合は、このセクションを省略できます。

 

ターゲット アプリは、データの処理に時間がかかるからといって、ユーザーにアプリの UI を見続けてもらうわけにはいきません。代わりに、ShareOperation オブジェクトを使って、アプリがまだ動作中であることをシステムに通知する必要があります。そうすれば、ユーザーはアプリの UI を閉じて、それまで行っていた作業に戻ることができます。その間、アプリはデータの処理をバックグラウンドで続けます。

shareOperation.reportStarted();

reportStarted を呼び出したら、ユーザーはアプリをそれ以上操作できなくなります。したがって、このオブジェクトの呼び出しは、ユーザーがアプリを閉じても問題がない状況でのみ行ってください。

長時間共有が行われている状況では、アプリが DataPackage オブジェクトからすべてのデータを取得する前に、ユーザーがソース アプリを閉じる可能性があります。そのため、アプリが必要なデータを取得したタイミングをシステムに通知することをお勧めします。こうすると、システムは必要に応じてソース アプリを中断または終了できます。

shareOperation.reportDataRetreived();

問題が発生した場合には、reportError を呼び出して、エラー メッセージをシステムに送ることもできます。ユーザーは、共有の状態を確認したときにこのメッセージを目にします。reportError を呼び出すと、すぐにアプリがシャットダウンし、共有が終了します。この場合、ユーザーはアプリでの同じコンテンツの共有をやり直す必要があります。エラーの中にはそれほど重大ではないものも含まれ、シナリオによっては、共有操作を終了しなくても済む場合もあります。その場合は、reportError を呼び出さずに、共有を続けることができます。

shareOperation.reportError("Could not reach the server! Try again later.");

これらのメソッドを使う場合は、通常、前に説明した順序で呼び出し、1 回しか呼び出せません。ただし、ターゲット アプリが reportStarted の前に reportDataRetrieved を呼び出すことができる場合があります。たとえば、アプリがアクティブ化ハンドラーのタスクの一部としてデータを受信できるが、ユーザーが [共有] ボタンをクリックするまで reportStarted を呼び出さない場合です。

この種類の共有が稼動している状況を確認するには、コンテンツ共有ターゲット アプリ サンプルをご覧ください。

5. 共有が完了したことの報告

最後に、アプリによる共有コンテンツの処理が正常に完了したときは、reportCompleted を呼び出します。

shareOperation.reportCompleted();

アプリは、共有が完了したことを報告すると終了します。

注  

QuickLink は Windows Phone 8.1 ではサポートされません。Windows Phone ストア アプリでは、共有操作の一部として QuickLink を受け取ることはできますが、これらのリンクは自動的に無視されます。

ユーザーがアプリで共有コンテンツを受け取ることを選んだときは、QuickLink を作成することを強くお勧めします。QuickLink は、情報をアプリと簡単に共有できるようにするショートカットのようなものです。たとえば、アプリでは、あらかじめ友人のメール アドレスが構成された新しいメール メッセージを開く QuickLink を作成できます。

ユーザーがアプリで共有コンテンツを受け取ることを選んだときは、QuickLink を作成することを強くお勧めします。QuickLink は、情報をアプリと簡単に共有できるようにするショートカットです。たとえば、アプリでは、あらかじめ友人のメール アドレスが構成された新しいメール メッセージを開く QuickLink を作成できます。

QuickLink には、タイトル、アイコン、ID が必要です。タイトル (「母へのメール」など) とアイコンは、ユーザーが共有チャームをタップすると表示されます。ID は、どの QuickLink が選ばれたかを識別するためにアプリが使うものです。アプリは、QuickLink を作成すると、ShareOperation オブジェクトの reportCompleted メソッドを呼び出して QuickLink をシステムに返します。次に例を示します。

function reportCompleted() {
    var quickLink = new Windows.ApplicationModel.DataTransfer.ShareTarget.QuickLink();
    quickLink.id = "123456789";
    quickLink.title = id("quickLinkTitle").value;

    // For quicklinks, the supported FileTypes and DataFormats are set independently from the manifest.
    var dataFormats = Windows.ApplicationModel.DataTransfer.StandardDataFormats;
    quickLink.supportedFileTypes.replaceAll(["*"]);
    quickLink.supportedDataFormats.replaceAll([dataFormats.text, dataFormats.uri, dataFormats.bitmap, 
        dataFormats.storageItems, dataFormats.html, customFormatName]);

    Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\user.png").then(function (iconFile) {
        quickLink.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(iconFile);
        shareOperation.reportCompleted(quickLink);
    });
}

アプリで QuickLink の ID と対応するユーザー データを格納する必要があることを忘れないでください。ユーザーが QuickLink をタップすると、ShareOperation.quickLinkId プロパティを介してその ID を取得できます。QuickLink への共有が成功した場合は、reportCompleted を呼び出すときに、同じ QuickLink を返す必要があります。

要約と次のステップ

以上で、共有コンテンツを受け取る方法と、QuickLink を作成してユーザーがコンテンツをアプリと共有できるようにする、お勧めの方法を説明しました。

さらに詳しく学習するか、共有をアプリに追加する方法に関する具体的な例を参照するには、次のトピックをご覧ください。

注  共有ターゲット アプリのデバッグは他の種類のアプリのデバッグとは異なります。詳しくは、「ターゲット アプリのデバッグに関するガイドライン」をご覧ください。

 

関連トピック

共有のためのデータ形式の選択

コンテンツの共有のガイドラインとチェック リスト

クイック スタート: コンテンツの共有