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

[アーティクル]
08/02/2024

ウィジェットホストに表示するには、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 を指定します。

属性	種類	Required	説明	規定値
ClassId	GUID	はい	ウィジェットプロバイダーを実装する CreateInstance サーバーの CLSID。	該当なし

ActivateApplication

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

定義

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

定義

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

属性	種類	Required	説明	既定値
Id	string	はい	ウィジェットを特定する ID。この値は、ウィジェットピッカーのナビゲーションバーにも表示されます。ウィジェットプロバイダーの実装では、この文字列を使用して、各操作で参照されるアプリのウィジェットを決定または指定します。この文字列は、アプリマニフェストファイル内で定義されているすべてのウィジェットに対して一意である必要があります。	該当なし
表示名	string	はい	ウィジェットホストに表示されるウィジェットの名前。	該当なし
説明	string	はい	ウィジェットの簡単な説明。	該当なし
AllowMultiple	boolean	いいえ	このウィジェットのインスタンスが 1 つだけサポートされている場合は false に設定します。この属性は省略可能で、既定値は true です。	true
IsCustomizable	boolean	いいえ	Windows App SDK 1.4 には導入されていません。アプリがウィジェットのカスタマイズをサポートしている場合は true に設定します。これにより、ウィジェットの省略記号メニューに [ウィジェットのカスタマイズ] ボタンが表示されます。	false
AdditionalInfoUri	string	いいえ	ユーザーがウィジェットフレームのタイトルバーをクリックしたとき、またはコンテキストメニューの Powered by 要素をクリックしたときに使用されるウィジェットに関連付けることができる URI。	該当なし
ExcludedRegions	string	いいえ	ウィジェットを使用できないリージョンの一覧。ウィジェットは ExcludedRegions または ExclusiveRegions を指定できますが 1 つのウィジェット定義で両方を指定することはできません。属性の値は、2 つの文字領域コードのコンマ区切りのリストです。	該当なし
ExclusiveRegions	string	いいえ	ウィジェットを使用できる唯一のリージョンの一覧。ウィジェットでは、 ExcludedRegions または ExclusiveRegions を指定できますが両方を単一のウィジェット定義で指定することはできません。属性の値は、2 つの文字領域コードのコンマ区切りのリストです。	該当なし

機能

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

機能

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

サイズ

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

属性	種類	Required	説明	規定値
名前	string	はい	ウィジェットでサポートされているサイズを指定します。値は、"小"、"中"、"大" のいずれかである必要があります	該当なし

ThemeResources

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

アイコン

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

アイコン

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

属性	種類	Required	説明	規定値
Path	string	はい	アイコンイメージファイルに対するパッケージ相対パス。	該当なし

スクリーンショット

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

スクリーンショット

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

Note

ウィジェットのスクリーンショットは、現在のプレビューリリースのウィジェットボードの [ウィジェットの追加] ダイアログには表示されません。

属性	種類	Required	説明	規定値
Path	string	はい	スクリーンショットイメージファイルに対するパッケージ相対パス。	該当なし
DisplayAltText	string	いいえ	アクセシビリティのためのイメージの代替テキスト。	該当なし

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"
            AdditionalInfoUri="https://contoso.com/widgets/Weather"
            ExclusiveRegions="US,UK"
            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>

次の方法で共有

アプリの拡張機能

要素の階層

WidgetProvider

WidgetProviderIcons

ライセンス認証

CreateInstance

ActivateApplication

定義

定義

機能

機能

サイズ

ThemeResources

アイコン

アイコン

スクリーンショット

スクリーンショット

DarkMode

LightMode

例

その他のリソース

次の方法で共有

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

アプリの拡張機能

要素の階層

WidgetProvider

WidgetProviderIcons

ライセンス認証

CreateInstance

ActivateApplication

定義

定義

機能

機能

サイズ

ThemeResources

アイコン

アイコン

スクリーンショット

スクリーンショット

DarkMode

LightMode

例

その他のリソース

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