Bagikan melalui

Menambahkan dukungan My People ke aplikasi

  • Artikel

Penting

Orang saya tidak lagi didukung di versi Windows 11 dan Windows 10 dengan KB5034203 diterapkan.

Catatan

Pada Pembaruan Windows 10 Mei 2019 (versi 1903), penginstalan Windows 10 baru tidak akan lagi menampilkan 'Orang di taskbar' secara default. Pelanggan dapat mengaktifkan fitur dengan mengklik kanan pada taskbar dan menekan "Tampilkan Orang di taskbar." Pengembang tidak disarankan untuk menambahkan dukungan Orang Saya ke aplikasi mereka, dan harus mengunjungi Blog Pengembang Windows untuk informasi selengkapnya tentang mengoptimalkan aplikasi untuk Windows 10.

Fitur Orang Saya memungkinkan pengguna menyematkan kontak dari aplikasi langsung ke taskbar mereka, yang membuat objek kontak baru yang dapat berinteraksi dengan mereka dalam beberapa cara. Artikel ini memperlihatkan bagaimana Anda dapat menambahkan dukungan untuk fitur ini, memungkinkan pengguna menyematkan kontak langsung dari aplikasi Anda. Saat kontak disematkan, jenis interaksi pengguna baru akan tersedia, seperti berbagi dan pemberitahuan Orang Saya.

Orang saya mengobrol

Persyaratan

  • Windows 10 dan Microsoft Visual Studio 2019. Untuk detail penginstalan, lihat Menyiapkan Visual Studio.
  • Pengetahuan dasar tentang C# atau bahasa pemrograman berorientasi objek serupa. Untuk mulai menggunakan C#, lihat Membuat aplikasi "Halo, dunia".

Gambaran Umum

Ada tiga hal yang perlu Anda lakukan untuk mengaktifkan aplikasi Anda untuk menggunakan fitur Orang Saya:

  1. Nyatakan dukungan untuk kontrak aktivasi shareTarget dalam manifes aplikasi Anda.
  2. Buat anotasi kontak yang dapat dibagikan pengguna menggunakan aplikasi Anda.
  3. Mendukung beberapa instans aplikasi Anda yang berjalan secara bersamaan. Pengguna harus dapat berinteraksi dengan versi lengkap aplikasi Anda saat menggunakannya di panel kontak. Mereka bahkan dapat menggunakannya di beberapa panel kontak sekaligus. Untuk mendukung hal ini, aplikasi Anda harus dapat menjalankan beberapa tampilan secara bersamaan. Untuk mempelajari cara melakukannya, lihat artikel "tampilkan beberapa tampilan untuk aplikasi".

Ketika Anda telah melakukan ini, aplikasi Anda akan muncul di panel kontak untuk kontak yang dianotasi.

Mendeklarasikan dukungan untuk kontrak

Untuk mendeklarasikan dukungan untuk kontrak Orang Saya, buka aplikasi Anda di Visual Studio. Dari Penjelajah Solusi, klik kanan Package.appxmanifest dan pilih Buka Dengan. Dari menu, pilih EDITOR XML (Teks) dan klik OK. Buat perubahan berikut pada manifes:

Sebelum

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10">

	<Applications>
	    <Application Id="MyApp"
	      Executable="$targetnametoken$.exe"
	      EntryPoint="My.App">
	    </Application>
	</Applications>

Sesudah

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap4="http://schemas.microsoft.com/appx/manifest/uap/windows10/4">

	<Applications>
	    <Application Id="MyApp"
	      Executable="$targetnametoken$.exe"
	      EntryPoint="My.App">
	      <Extensions>
	        <uap4:Extension Category="windows.contactPanel" />
	      </Extensions>
	    </Application>
	</Applications>

Dengan penambahan ini, aplikasi Anda sekarang dapat diluncurkan melalui jendela. Kontrak ContactPanel , yang memungkinkan Anda berinteraksi dengan panel kontak.

Menganotasi kontak

Untuk memperbolehkan kontak dari aplikasi Anda muncul di bilah tugas melalui panel Orang Saya, Anda perlu menulisnya ke penyimpanan kontak Windows. Untuk mempelajari cara menulis kontak, lihat sampel Kartu Kontak.

Aplikasi Anda juga harus menulis anotasi ke setiap kontak. Anotasi adalah potongan data dari aplikasi Anda yang terkait dengan kontak. Anotasi harus berisi kelas yang dapat diaktifkan yang sesuai dengan tampilan yang Anda inginkan di anggota ProviderProperties-nya, dan menyatakan dukungan untuk operasi ContactProfile.

Anda dapat membuat anotasi kontak kapan saja saat aplikasi berjalan, tetapi umumnya Anda harus membuat anotasi kontak segera setelah ditambahkan ke penyimpanan kontak Windows.

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 5))
{
	// Create a new contact annotation
	ContactAnnotation annotation = new ContactAnnotation();
	annotation.ContactId = myContact.Id;

	// Add appId and contact panel support to the annotation
	String appId = "MyApp_vqvv5s4y3scbg!App";
	annotation.ProviderProperties.Add("ContactPanelAppID", appId);
	annotation.SupportedOperations = ContactAnnotationOperations.ContactProfile;

	// Save annotation to contact annotation list
	// Windows.ApplicationModel.Contacts.ContactAnnotationList 
	await contactAnnotationList.TrySaveAnnotationAsync(annotation));
}

"appId" adalah Nama Keluarga Paket, diikuti oleh '!' dan ID kelas yang dapat diaktifkan. Untuk menemukan Nama Keluarga Paket Anda, buka Package.appxmanifest menggunakan editor default, dan lihat di tab "Kemasan". Di sini, "Aplikasi" adalah kelas yang dapat diaktifkan yang sesuai dengan tampilan startup aplikasi.

Perbolehkan kontak mengundang calon pengguna baru

Secara default, aplikasi Anda hanya akan muncul di panel kontak untuk kontak yang telah Anda anotasi secara khusus. Hal ini untuk menghindari kebingungan dengan kontak yang tidak dapat berinteraksi melalui aplikasi Anda. Jika Anda ingin aplikasi Anda muncul untuk kontak yang tidak diketahui aplikasi Anda (untuk mengundang pengguna untuk menambahkan kontak tersebut ke akun mereka, misalnya), Anda dapat menambahkan yang berikut ini ke manifes Anda:

Sebelum

<Applications>
	<Application Id="MyApp"
	  Executable="$targetnametoken$.exe"
	  EntryPoint="My.App">
	  <Extensions>
    	<uap4:Extension Category="windows.contactPanel" />
	  </Extensions>
	</Application>
</Applications>

Sesudah

<Applications>
	<Application Id="MyApp"
	  Executable="$targetnametoken$.exe"
	  EntryPoint="My.App">
	  <Extensions>
		<uap4:Extension Category="windows.contactPanel">
	    	<uap4:ContactPanel SupportsUnknownContacts="true" />
		</uap4:Extension>
	  </Extensions>
	</Application>
</Applications>

Dengan perubahan ini, aplikasi Anda akan muncul sebagai opsi yang tersedia di panel kontak untuk semua kontak yang telah disematkan pengguna. Ketika aplikasi Anda diaktifkan menggunakan kontrak panel kontak, Anda harus memeriksa untuk melihat apakah kontak adalah salah satu yang diketahui aplikasi Anda. Jika tidak, Anda harus menampilkan pengalaman pengguna baru aplikasi Anda.

Panel kontak Orang Saya

Dukungan untuk aplikasi email

Jika Anda menulis aplikasi email, Anda tidak perlu membuat anotasi setiap kontak secara manual. Jika Anda mendeklarasikan dukungan untuk panel kontak dan untuk mailto: protokol, aplikasi Anda akan secara otomatis muncul untuk pengguna dengan alamat email.

Berjalan di panel kontak

Sekarang setelah aplikasi Anda muncul di panel kontak untuk beberapa atau semua pengguna, Anda perlu menangani aktivasi dengan kontrak panel kontak.

override protected void OnActivated(IActivatedEventArgs e)
{
    if (e.Kind == ActivationKind.ContactPanel)
    {
        // Create a Frame to act as the navigation context and navigate to the first page
        var rootFrame = new Frame();

        // Place the frame in the current Window
        Window.Current.Content = rootFrame;

        // Navigate to the page that shows the Contact UI.
        rootFrame.Navigate(typeof(ContactPage), e);

        // Ensure the current window is active
        Window.Current.Activate();
    }
}

Ketika aplikasi Anda diaktifkan dengan kontrak ini, aplikasi akan menerima objek ContactPanelActivatedEventArgs. Ini berisi ID Kontak yang coba berinteraksi dengan aplikasi Anda saat diluncurkan, dan objek ContactPanel . Anda harus menyimpan referensi ke objek ContactPanel ini, yang akan memungkinkan Anda berinteraksi dengan panel.

Objek ContactPanel memiliki dua peristiwa yang harus didengarkan aplikasi Anda:

  • Peristiwa LaunchFullAppRequested dikirim ketika pengguna telah memanggil elemen UI yang meminta agar aplikasi lengkap Anda diluncurkan di jendelanya sendiri. Aplikasi Anda bertanggung jawab untuk meluncurkan dirinya sendiri, melewati semua konteks yang diperlukan. Anda bebas untuk melakukan ini sesuka Anda (misalnya, melalui peluncuran protokol).
  • Peristiwa Penutupan dikirim ketika aplikasi Anda akan ditutup, memungkinkan Anda menyimpan konteks apa pun.

Objek ContactPanel juga memungkinkan Anda untuk mengatur warna latar belakang header panel kontak (jika tidak diatur, itu akan default ke tema sistem) dan untuk secara terprogram menutup panel kontak.

Mendukung badging pemberitahuan

Jika Anda ingin kontak yang disematkan ke taskbar di-badged saat pemberitahuan baru tiba dari aplikasi Anda yang terkait dengan orang tersebut, maka Anda harus menyertakan parameter petunjuk-orang dalam pemberitahuan toast Anda dan pemberitahuan My People yang ekspresif.

Badging pemberitahuan orang

Untuk memberi lencana kontak, simpul toast tingkat atas harus menyertakan parameter petunjuk orang untuk menunjukkan pengiriman atau kontak terkait. Parameter ini dapat memiliki salah satu nilai berikut:

Berikut adalah contoh cara mengidentifikasi pemberitahuan toast terkait dengan orang tertentu:

<toast hint-people="mailto:johndoe@mydomain.com">
    <visual lang="en-US">
        <binding template="ToastText01">
            <text>John Doe posted a comment.</text>
        </binding>
    </visual>
</toast>

Catatan

Jika aplikasi Anda menggunakan API ContactStore dan menggunakan properti StoredContact.RemoteId untuk menautkan kontak yang disimpan di PC dengan kontak yang disimpan dari jarak jauh, sangat penting bahwa nilai untuk properti RemoteId stabil dan unik. Ini berarti bahwa ID jarak jauh harus secara konsisten mengidentifikasi satu akun pengguna dan harus berisi tag unik untuk menjamin bahwa ID jarak jauh kontak lain di PC tidak bertentangan, termasuk kontak yang dimiliki oleh aplikasi lain. Jika ID jarak jauh yang digunakan oleh aplikasi Anda tidak dijamin stabil dan unik, Anda dapat menggunakan kelas RemoteIdHelper yang ditampilkan nanti dalam topik ini untuk menambahkan tag unik ke semua ID jarak jauh Anda sebelum Anda menambahkannya ke sistem. Atau Anda dapat memilih untuk tidak menggunakan properti RemoteId sama sekali dan sebaliknya Anda membuat properti perluasan kustom untuk menyimpan ID jarak jauh untuk kontak Anda.

Kelas PinnedContactManager

PinnedContactManager digunakan untuk mengelola kontak mana yang disematkan ke taskbar. Kelas ini memungkinkan Anda menyematkan dan melepas pin kontak, menentukan apakah kontak disematkan, dan menentukan apakah penyematan pada permukaan tertentu didukung oleh sistem yang saat ini dijalankan aplikasi Anda.

Anda dapat mengambil objek PinnedContactManager menggunakan metode GetDefault :

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

Menyematkan dan melepas pin kontak

Anda sekarang dapat menyematkan dan melepas pin kontak menggunakan PinnedContactManager yang baru saja Anda buat. Metode RequestPinContactAsync dan RequestUnpinContactAsync memberi pengguna dialog konfirmasi, sehingga mereka harus dipanggil dari utas Application Single-Threaded Apartment (ASTA, atau UI) Anda.

async void PinContact (Contact contact)
{
    await pinnedContactManager.RequestPinContactAsync(contact,
                                                      PinnedContactSurface.Taskbar);
}

async void UnpinContact (Contact contact)
{
    await pinnedContactManager.RequestUnpinContactAsync(contact,
                                                        PinnedContactSurface.Taskbar);
}

Anda juga dapat menyematkan beberapa kontak secara bersamaan:

async Task PinMultipleContacts(Contact[] contacts)
{
    await pinnedContactManager.RequestPinContactsAsync(
        contacts, PinnedContactSurface.Taskbar);
}

Catatan

Saat ini tidak ada operasi batch untuk melepas semat kontak.

Catatan:

Lihat juga