ウィジェット プロバイダーのパッケージ マニフェスト (XML 形式)

ウィジェット ホストに表示するには、Windows ウィジェットをサポートするアプリでそのウィジェット プロバイダーをシステムに登録する必要があります。 Win32 アプリの場合、現在サポートされているのはパッケージ アプリのみで、ウィジェット プロバイダーはアプリ パッケージ マニフェスト ファイルに登録情報を指定します。 この記事では、ウィジェット登録の XML 形式について説明します。 Win32 ウィジェット プロバイダーのパッケージ マニフェストの例のコード一覧については、「例」セクションを参照してください。

アプリの拡張機能

アプリ パッケージ マニフェスト ファイルでは、Windows アプリのさまざまな拡張機能と機能がサポートされています。 アプリケーション パッケージ マニフェストの形式は、パッケージ マニフェスト スキーマ リファレンスに記載されているスキーマのセットによって定義されます。 ウィジェット プロバイダーは、uap3:AppExtension 内で登録情報を宣言します。 拡張機能の Name 属性は、"com.microsoft.windows.widgets" に設定する必要があります。

ウィジェット プロバイダーには、uap3:AppExtension の子として uap3:Properties を含める必要があります。 パッケージ マニフェスト スキーマでは、適切な形式の XML を必要とする以外に、uap3:Properties 要素の構造は適用されません。 この記事の残りの部分では、ウィジェット プロバイダーを正常に登録するためにウィジェット ホストで想定される XML 形式について説明します。

<uap3:Extension Category="windows.appExtension">
  <uap3:AppExtension Name="com.microsoft.windows.widgets" DisplayName="WidgetTestApp" Id="ContosoWidgetApp" PublicFolder="Public">
    <uap3:Properties>
    <!-- Widget provider registration content goes here -->
    </uap3:Properties>
  </uap3:AppExtension>
</uap3:Extension>

要素の階層

WidgetProvider

  ProviderIcons

    アイコン

  ライセンス認証

    CreateInstance

    ActivateApplication

  定義

    定義

      機能

        機能

          サイズ

      ThemeResources

        アイコン

          アイコン

        スクリーンショット

          スクリーンショット

        DarkMode

          アイコン

            アイコン

          スクリーンショット

            スクリーンショット

        LightMode

          アイコン

            アイコン

          スクリーンショット

            スクリーンショット

WidgetProvider

ウィジェット プロバイダー登録情報のルート要素。

WidgetProviderIcons

ウィジェット プロバイダー アプリを表すアイコンを指定します。

ライセンス認証

ウィジェット プロバイダーのアクティブ化情報を指定します。 マニフェストで CreateInstance と ActivateApplication の両方が指定されている場合は、CreateInstance が優先されます。

CreateInstance

CreateInstance は、IWidgetProvider インターフェイスを実装する Win32 ベースのウィジェット プロバイダーに指定する必要があります。 システムは、CoCreateInstance の呼び出しでインターフェイスをアクティブ化します。 ClassId 属性は、IWidgetProvider インターフェイスを実装する CreateInstance サーバーの CLSID を指定します。

ActivateApplication

ActivateApplication を指定すると、ウィジェット プロバイダーはコマンド ラインを介してアクティブ化され、引数は base64url でエンコードされた JSON 文字列として指定されます。 ウィジェット プロバイダーは、 CreateInstance アクティブ化の種類を使用することをお勧めします。 ActivateApplication コマンド ライン形式の詳細については、「ウィジェット プロバイダー ActivateApplication プロトコル」を参照してください。

定義

1 つ以上のウィジェット登録のコンテナー要素。

定義

単一ウィジェットの登録を表します。

機能

省略可能。 単一ウィジェットの機能を指定します。 機能が宣言されていない場合は、"大" サイズを指定する 1 つの機能が既定で追加されます。

機能

ウィジェットの機能を指定します。

サイズ

関連付けられているウィジェットでサポートされているサイズを指定します。

ThemeResources

ウィジェットのテーマ リソースを指定します。

アイコン

1 つ以上の Icon 要素に対応するコンテナー要素。

アイコン

必須。 ウィジェットの属性領域に表示されるアイコンを指定します。

スクリーンショット

必須。 ウィジェットの 1 つ以上のスクリーンショットを指定します。

スクリーンショット

必須。 ウィジェットのスクリーンショットを指定します。 このスクリーンショットは、ユーザーがウィジェット ホストに追加するウィジェットを選択しているときに、[ウィジェットの追加] ダイアログのウィジェット ホストに表示されます。 以下に一覧表示したオプションの DarkMode 要素または LightMode 要素のスクリーンショットを指定すると、ウィジェット ホストは現在のデバイス テーマに一致するスクリーンショットを使用します。 現在のデバイス テーマのスクリーンショットを指定しない場合は、この Screenshot 要素で指定されているイメージが使用されます。 スクリーンショットの画像の設計要件とローカライズされたスクリーンショットの名前付け規則については、「ウィジェット ピッカーと統合する」をご覧ください。

DarkMode

省略可能。 デバイスでダーク モードがアクティブな場合のテーマ リソースを指定します。 オプションの DarkMode 要素で 1 つ以上のスクリーンショット イメージを指定すると、デバイスがダーク モードのときにウィジェット ホストでこれらのスクリーンショットが選択されます。 ダーク モードのイメージを指定しない場合、ウィジェット ホストは、前述の必須の最上位のスクリーンショット要素を使用します。 スクリーンショットの画像の設計要件とローカライズされたスクリーンショットの名前付け規則については、「ウィジェット ピッカーと統合する」をご覧ください。

LightMode

省略可能。 デバイスでライト モードがアクティブな場合のテーマ リソースを指定します。 オプションの DarkMode 要素で 1 つ以上のスクリーンショット イメージを指定すると、デバイスがライト モードのときにウィジェット ホストでこれらのスクリーンショットが選択されます。 ライト モードのイメージを指定しない場合、ウィジェット ホストは、前述の必須の最上位のスクリーンショット要素を使用します。 スクリーンショットの画像の設計要件とローカライズされたスクリーンショットの名前付け規則については、「ウィジェット ピッカーと統合する」をご覧ください。

例

次のコード例は、ウィジェット パッケージ マニフェスト XML 形式の使用方法を示しています。

<uap3:Extension Category="windows.appExtension">
  <uap3:AppExtension Name="com.microsoft.windows.widgets" DisplayName="Widget Test App" Id="ContosoWidgetApp" PublicFolder="Public">
    <uap3:Properties>
      <WidgetProvider>
        <ProviderIcons>
            <Icon Path="Images\StoreIcon.png" />
        </ProviderIcons>
        <Activation>
          <!-- App exports COM interface which implements IWidgetProvider -->
          <CreateInstance ClassId="XXXXXXXX-XXXX-XXXX-XXXX-D3397A3FF15C" />
        </Activation>
        <Definitions>
          <Definition
            Id="Weather_Widget"
            DisplayName="Microsoft Weather Widget"
            Description="Weather Widget Description"
            AllowMultiple="true">
            <Capabilities>
              <Capability>
                 <Size Name="small" />
              </Capability>
              <Capability>
                 <Size Name="medium" />
              </Capability>
              <Capability>
                 <Size Name="large" />
              </Capability>
            </Capabilities>

            <ThemeResources>
              <Icons>
                <Icon Path="Assets\icon.png" />
                <Icon Path="Assets\icon.gif" />
              </Icons>
              <Screenshots>
                <Screenshot Path="Assets\background.png" DisplayAltText ="For accessibility"/>
              </Screenshots>

              <!-- DarkMode and LightMode are optional -->
              <DarkMode>
                <Icons>
                  <Icon Path="Assets\dark.png" />
                </Icons>
                <Screenshots>
                  <Screenshot Path="Assets\darkBackground.png" DisplayAltText ="For accessibility"/>
                </Screenshots>
              </DarkMode>

              <LightMode>
                <Icons>
                  <Icon Path="Assets\light.png" />
                </Icons>
                <Screenshots>
                  <Screenshot Path="Assets\lightBackground.png"/>
                </Screenshots>
              </LightMode>
            </ThemeResources>
          </Definition>
        </Definitions>
      </WidgetProvider>
    </uap3:Properties>
  </uap3:AppExtension>
</uap3:Extension>