將朋友圈支援新增至應用程式
重要
Windows 11 和已套用 KB5034203 的 Windows 10 版本不再支援朋友圈。
注意
從 Windows 10 的 2019 年 5 月更新 (版本 1903) 起，新的 Windows 10 安裝不會再繼續預設「將連絡人顯示在工作列中」。 客戶可以在工作列上按一下滑鼠右鍵，然後按下 [在工作列上顯示連絡人] 來啟用此功能。 開發人員不建議將朋友圈支援新增至其應用程式，並應該前往 Windows 開發人員部落格以取得最佳化 Windows 10 應用程式的詳細資訊。
朋友圈功能可讓使用者將連絡人從應用程式直接釘選到其工作列，這會建立一個新的連絡人物件，使用者能以數種方式與之互動。 本文說明如何新增此功能的支援，讓使用者可以直接從您的應用程式釘選連絡人。 釘選連絡人時，新的使用者互動類型就會變成可用，例如 [朋友圈分享] 和 [通知]。
需求
- Windows 10 和 Microsoft Visual Studio 2019。 如需安裝的詳細資料，請參閱開始設定 Visual Studio。
- C# 或類似物件導向程式設計語言的基本知識。 若要開始使用 C#，請參閱建立 "Hello, world" 應用程式。
概觀
您需要執行三件事，才能讓應用程式使用朋友圈功能：
- 在應用程式資訊清單中宣告對 shareTarget 啟動合約的支援。
- 標註使用者可以使用您的應用程式分享的連絡人。
- 支援同時執行多個應用程式的執行個體。 當使用者在連絡人面板中使用您的應用程式時，必須要能夠與應用程式的完整版本互動。 他們甚至可以同時在多個連絡人面板中使用該應用程式。 若要支援此功能，您的應用程式必須能夠同時執行多個檢視。 若要了解具體做法，請參閱「顯示應用程式的多重檢視」一文。
當您完成此步驟時，您的應用程式會出現在已標註連絡人的連絡人面板中。
宣告對合約的支援
若要宣告對朋友圈合約的支援，請在 Visual Studio 中開啟您的應用程式。 在 [檔案總管] 中，以滑鼠右鍵按一下 Package.appxmanifest 並選取 [開啟方式]。 從功能表中，選取 [XML (文字) 編輯器]，然後按一下 [確定]。 對資訊清單進行下列變更：
之前
<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>
之後
<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>
此外，您的應用程式現在可以透過 windows.ContactPanel 合約啟動，這可讓您與連絡人面板互動。
標註連絡人
若要允許來自您應用程式的連絡人透過 [朋友圈] 窗格出現在工作列中，您必須將它們寫入 Windows 連絡人存放區。 若要了解如何寫入連絡人，請參閱連絡人卡片範例。
您的應用程式也必須將標註寫入每個連絡人。 標註是由應用程式所提供，與連絡人相關聯的的資料片段。 標註必須在其 ProviderProperties 成員中，包含對應至所需檢視的可啟動類別，並宣告對 ContactProfile 作業的支援。
您可以在應用程式執行時隨時標註連絡人，但通常應該在連絡人新增至 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” 是套件系列名稱，後面接著 ‘!’ 以及可啟動類別識別碼。 若要尋找您的套件系列名稱，請使用預設編輯器開啟 Package.appxmanifest，然後查看 [封裝] 索引標籤。在這裡，「應用程式」是對應至應用程式啟動檢視的可啟動類別。
允許連絡人邀請新的潛在使用者
根據預設，您的應用程式只會針對您特別標註的連絡人，出現在連絡人面板中。 這是為了避免混淆無法透過您應用程式互動的連絡人。 如果您想要讓應用程式在遇到您應用程式不知道的連絡人時出現 (例如，邀請使用者將該連絡人新增至其帳戶)，您可以將下列內容新增至您的資訊清單：
之前
<Applications>
<Application Id="MyApp"
Executable="$targetnametoken$.exe"
EntryPoint="My.App">
<Extensions>
<uap4:Extension Category="windows.contactPanel" />
</Extensions>
</Application>
</Applications>
之後
<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>
透過這項變更，您的應用程式會在遇到使用者已釘選的所有連絡人時，成為他們連絡人面板中的可用選項。 當您的應用程式使用連絡人面板合約來啟動時，您應該檢查連絡人是否為應用程式知道的連絡人。 如果不是，您應該顯示應用程式的新使用者體驗。
支援電子郵件應用程式
如果您要撰寫電子郵件應用程式，則不需要手動標註每個連絡人。 如果您宣告對連絡人窗格和 mailto: 通訊協定的支援，您的應用程式會自動在遇到具有電子郵件地址的使用者時出現。
在連絡人面板中執行
現在您的應用程式會出現在部分或所有使用者的連絡人面板中，您需要使用連絡人面板合約來處理啟動。
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();
}
}
當您的應用程式使用此合約啟用時，它會收到 ContactPanelActivatedEventArgs 物件。 這包含應用程式在啟動時嘗試與其互動的連絡人識別碼，以及 ContactPanel 物件。 您應該保留此 ContactPanel 物件的參照，這可讓您與面板互動。
ContactPanel 物件有兩個事件應該由應用程式接聽：
- 如果 UI 元素要求在自己的視窗中啟動您的完整應用程式，而使用者叫用了這個元素時，就會傳送 LaunchFullAppRequested 事件。 您的應用程式負責自行啟動，並傳遞所有必要的內容。 您可以自由決定如何完成此目標 (例如，透過通訊協定啟動)。
- Closing 事件會在您的應用程式即將關閉時傳送，讓您可儲存任何內容。
ContactPanel 物件也可讓您設定連絡人面板標頭的背景色彩 (如果未設定，則會預設為系統主題)，並以程式設計方式關閉連絡人面板。
支援通知徽章
如果您希望釘選到工作列的連絡人，從與該連絡人相關的應用程式收到新通知時獲得徽章，則必須在快顯通知以及顯現的朋友圈通知中包含 hint-people 參數。
若要給予連絡人徽章，最上層快顯通知節點必須包含 hint-people 參數，以指出寄出或相關的連絡人。 這個參數的值可以是下列任何一個：
- 電子郵件地址
- 電話號碼
- 例如 888-888-8888
- 遠端識別碼
- 例如 remoteid:1234
以下範例說明如何識別快顯通知與特定人員相關：
<toast hint-people="mailto:johndoe@mydomain.com">
<visual lang="en-US">
<binding template="ToastText01">
<text>John Doe posted a comment.</text>
</binding>
</visual>
</toast>
注意
如果您的應用程式使用 ContactStore API 也使用 StoredContact.RemoteId 屬性，將儲存在 PC 上的連絡人與遠端儲存的連絡人彼此連結，則 RemoteId 屬性的值必須是穩定且唯一的值。 這表示遠端識別碼必須一致地識別單一使用者帳戶，而且應該包含唯一標籤，以確保它不會與 PC 上其他連絡人的遠端識別碼衝突，包括其他應用程式所擁有的連絡人。 如果應用程式所使用的遠端識別碼無法保證是穩定且唯一的值，您可以使用本主題接下來介紹的 RemoteIdHelper 類別，以便在您將所有遠端識別碼新增至系統之前，將唯一標籤新增至這些遠端識別碼。 或者，您可以選擇完全不使用 RemoteId 屬性，而是建立自訂擴充屬性，以儲存連絡人的遠端識別碼。
PinnedContactManager 類別
PinnedContactManager 是用來管理將哪些連絡人釘選到工作列。 這個類別可讓您釘選和取消釘選連絡人、判斷是否已釘選某個連絡人，以及判斷目前執行應用程式的系統是否支援在特定介面上釘選。
您可以使用 GetDefault 方法擷取 PinnedContactManager 物件：
PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();
釘選和取消釘選連絡人
您現在可以使用剛才建立好的 PinnedContactManager，來釘選和取消釘選連絡人。 RequestPinContactAsync 和 RequestUnpinContactAsync 方法會為使用者提供確認對話方塊，因此必須從您的應用程式單一執行緒 Apartment (ASTA，或稱 UI) 執行緒來呼叫它們。
async void PinContact (Contact contact)
{
await pinnedContactManager.RequestPinContactAsync(contact,
PinnedContactSurface.Taskbar);
}
async void UnpinContact (Contact contact)
{
await pinnedContactManager.RequestUnpinContactAsync(contact,
PinnedContactSurface.Taskbar);
}
您也可以同時釘選多個連絡人：
async Task PinMultipleContacts(Contact[] contacts)
{
await pinnedContactManager.RequestPinContactsAsync(
contacts, PinnedContactSurface.Taskbar);
}
注意
目前沒有取消釘選連絡人的批次作業。
注意：