Format XML manifes paket penyedia widget

Untuk ditampilkan di host widget, aplikasi yang mendukung widget Windows harus mendaftarkan penyedia widget mereka dengan sistem. Untuk aplikasi Win32, hanya aplikasi paket yang saat ini didukung dan penyedia widget menentukan informasi pendaftaran mereka dalam file manifes paket aplikasi. Artikel ini mendanai format XML untuk pendaftaran widget. Lihat bagian Contoh untuk daftar kode manifes paket contoh untuk penyedia widget Win32.

Ekstensi aplikasi

File manifes paket aplikasi mendukung banyak ekstensi dan fitur yang berbeda untuk aplikasi Windows. Format manifes paket aplikasi didefinisikan oleh sekumpulan skema yang didokumentasikan dalam referensi skema manifes paket. Penyedia widget mendeklarasikan informasi pendaftaran mereka dalam uap3:AppExtension. Atribut Nama ekstensi harus diatur ke "com.microsoft.windows.widgets".

Penyedia widget harus menyertakan uap3:Properties sebagai anak dari uap3:AppExtension. Skema manifes paket tidak memberlakukan struktur elemen uap3:Properties selain membutuhkan XML yang terbentuk dengan baik. Sisa artikel ini menjelaskan format XML yang diharapkan host Widget agar berhasil mendaftarkan penyedia widget.

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

Hierarki elemen

WidgetProvider

  ProviderIcons

    Ikon

  Aktivasi

    CreateInstance

    AktifkanAplikasi

  Definisi

    Definisi

      Kemampuan

        Kemampuan

          Ukuran

      ThemeResources

        Ikon

          Ikon

        Cuplikan layar

          Cuplikan layar

        DarkMode

          Ikon

            Ikon

          Cuplikan layar

            Cuplikan layar

        LightMode

          Ikon

            Ikon

          Cuplikan layar

            Cuplikan layar

WidgetProvider

Elemen akar informasi pendaftaran penyedia widget.

Cuplikan layar dialog Tambahkan Widget di papan Widget. Ini menunjukkan dua kolom entri, masing-masing dengan ikon dan nama aplikasi, dengan tanda plus yang menunjukkan bahwa widget dapat ditambahkan

WidgetProviderIcons

Menentukan ikon yang mewakili aplikasi penyedia widget.

Aktivasi

Menentukan informasi aktivasi untuk penyedia widget. Jika CreateInstance dan ActivateApplication ditentukan dalam manifes, CreateInstance lebih diutamakan.

CreateInstance

CreateInstance harus ditentukan untuk penyedia widget berbasis Win32 yang mengimplementasikan antarmuka IWidgetProvider . Sistem akan mengaktifkan antarmuka dengan panggilan ke CoCreateInstance. Atribut ClassId menentukan CLSID untuk server CreateInstance yang mengimplementasikan antarmuka IWidgetProvider .

Atribut Jenis Wajib Deskripsi Nilai default
ClassId GUID Ya CLSID untuk server CreateInstance yang mengimplementasikan penyedia widget. T/A

AktifkanAplikasi

Ketika ActivateApplication ditentukan, penyedia widget diaktifkan melalui baris perintah, dengan argumen yang disediakan sebagai string JSON yang dikodekan base64url. Disarankan agar penyedia widget menggunakan jenis aktivasi CreateInstance . Untuk informasi tentang format baris perintah ActivateApplication , lihat Protokol ActivateApplication penyedia widget.

Definisi

Elemen kontainer untuk satu atau beberapa pendaftaran widget.

Definisi

Mewakili pendaftaran untuk satu widget.

Atribut Jenis Wajib Deskripsi Nilai default
Id string Ya ID yang mengidentifikasi widget. Nilai ini juga ditampilkan di bilah navigasi pemilih widget. Implementasi penyedia widget menggunakan string ini untuk menentukan atau menentukan widget aplikasi mana yang sedang dirujuk untuk setiap operasi. String ini harus unik untuk semua widget yang ditentukan dalam file manifes aplikasi. T/A
DisplayName string Ya Nama widget yang ditampilkan pada host widget. T/A
Keterangan string Ya Deskripsi singkat widget. T/A
AllowMultiple Boolean No Atur ke false jika hanya satu instans widget ini yang didukung. Atribut ini bersifat opsional dan nilai defaultnya benar. benar
IsCustomizable Boolean No Diperkenalkan dalam SDK Aplikasi Windows 1.4. Atur ke true jika aplikasi Anda mendukung kustomisasi widget. Ini menyebabkan tombol Sesuaikan widget ditampilkan di menu elipsis widget. salah
AdditionalInfoUri string No URI yang dapat dikaitkan dengan widget yang akan digunakan saat pengguna mengklik bilah judul bingkai widget atau saat mengklik elemen Powered by dari menu konteksnya. T/A
ExcludedRegions string No Daftar wilayah tempat widget tidak boleh tersedia. Widget dapat menentukan ExcludedRegions atau ExclusiveRegions tetapi tidak boleh menentukan keduanya dalam satu definisi widget. Nilai atribut adalah daftar yang dipisahkan koma dari dua kode wilayah karakter. T/A
ExclusiveRegions string No Daftar satu-satunya wilayah tempat widget harus tersedia. Widget dapat menentukan ExcludedRegions atau ExclusiveRegions tetapi tidak boleh menentukan keduanya dalam definisi widget tunggal. Nilai atribut adalah daftar yang dipisahkan koma dari dua kode wilayah karakter. T/A

Kemampuan

Opsional. Menentukan kemampuan untuk satu widget. Jika tidak ada kemampuan yang dideklarasikan, satu kemampuan yang menentukan ukuran "besar" ditambahkan secara default.

Kemampuan

Menentukan kemampuan untuk widget.

Ukuran

Menentukan ukuran yang didukung untuk widget terkait.

Atribut Jenis Wajib Deskripsi Nilai default
Nama string Ya Menentukan ukuran yang didukung untuk widget. Nilainya harus salah satu dari berikut ini: "kecil", "sedang", "besar" T/A

ThemeResources

Menentukan sumber daya tema untuk widget.

Ikon

Elemen kontainer untuk satu atau beberapa elemen Ikon .

Ikon

Harus diisi. Menentukan ikon yang ditampilkan di area atribusi widget.

Atribut Jenis Wajib Deskripsi Nilai default
Jalur string Ya Jalur relatif paket ke file gambar ikon. T/A

Cuplikan layar

Harus diisi. Menentukan satu atau beberapa cuplikan layar widget.

Cuplikan layar

Harus diisi. Menentukan cuplikan layar untuk widget. Cuplikan layar ini ditampilkan di host widget dalam dialog Tambahkan Widget saat pengguna memilih widget untuk ditambahkan ke host widget. Jika Anda memberikan cuplikan layar untuk elemen DarkMode atau LightMode opsional yang tercantum di bawah ini, maka host widget akan menggunakan cuplikan layar yang cocok dengan tema perangkat saat ini. Jika Anda tidak memberikan cuplikan layar untuk tema perangkat saat ini, gambar yang disediakan dalam elemen Cuplikan Layar ini akan digunakan. Untuk informasi tentang persyaratan desain untuk gambar cuplikan layar dan konvensi penamaan untuk cuplikan layar yang dilokalkan, lihat Mengintegrasikan dengan pemilih widget.

Catatan

Cuplikan layar widget tidak ditampilkan pada dialog tambahkan widget papan widget dalam rilis pratinjau saat ini..

Atribut Jenis Wajib Deskripsi Nilai default
Jalur string Ya Jalur relatif paket ke file gambar cuplikan layar. T/A
DisplayAltText string No Teks alt untuk gambar, untuk aksesibilitas. T/A

DarkMode

Opsional. Menentukan sumber daya tema ketika mode gelap aktif pada perangkat. Jika Anda menentukan satu atau beberapa gambar cuplikan layar di elemen DarkMode opsional, host widget akan memilih cuplikan layar ini saat perangkat berada dalam mode gelap. Jika Anda tidak memberikan gambar mode gelap, host widget akan menggunakan elemen Cuplikan Layar tingkat atas yang diperlukan yang dijelaskan di atas. Untuk informasi tentang persyaratan desain untuk gambar cuplikan layar dan konvensi penamaan untuk cuplikan layar yang dilokalkan, lihat Mengintegrasikan dengan pemilih widget.

LightMode

Opsional. Menentukan sumber daya tema ketika mode cahaya aktif pada perangkat. Jika Anda memberikan satu atau beberapa gambar cuplikan layar di elemen LightMode opsional, host widget akan memilih cuplikan layar ini saat perangkat dalam mode terang. Jika Anda tidak memberikan gambar mode ringan, host widget akan menggunakan elemen Cuplikan Layar tingkat atas yang diperlukan yang dijelaskan di atas. Untuk informasi tentang persyaratan desain untuk gambar cuplikan layar dan konvensi penamaan untuk cuplikan layar yang dilokalkan, lihat Mengintegrasikan dengan pemilih widget.

Contoh

Contoh kode berikut mengilustrasikan penggunaan format XML manifes paket widget.

<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>
  • Last updated on