將應用程式連結到連絡人卡片上的動作

發行項
03/19/2024

您的應用程式可以顯示在連絡人卡片或迷你連絡人卡片上的動作旁邊。使用者可以選擇您的應用程式來執行動作，例如開啟設定檔頁面、撥打電話或傳送訊息。

聯繫人卡片和迷你聯繫人卡片

若要開始，請尋找現有的連絡人或建立新的連絡人。接下來，建立標註和一些套件資訊清單項目，以描述您的應用程式支援哪些動作。然後，撰寫執行動作的程式碼。

如需更完整的範例，請參閱連絡人卡片整合範例。

尋找或建立聯絡人

如果您的應用程式要協助人們與他人聯繫，請搜尋 Windows 中的連絡人，然後標註這些連絡人。如果您的應用程式要管理連絡人，可以將連絡人新增至 Windows 連絡人清單，然後標註這些連絡人。

尋找連絡人

使用名稱、電子郵件地址或電話號碼來尋找連絡人。

ContactStore contactStore = await ContactManager.RequestStoreAsync();

IReadOnlyList<Contact> contacts = null;

contacts = await contactStore.FindContactsAsync(emailAddress);

Contact contact = contacts[0];

建立連絡人

如果您的應用程式更像是通訊錄，請建立連絡人，然後將他們新增至連絡人清單。

Contact contact = new Contact();
contact.FirstName = "TestContact";

ContactEmail email = new ContactEmail();
email.Address = "TestContact@contoso.com";
email.Kind = ContactEmailKind.Other;
contact.Emails.Add(email);

ContactPhone phone = new ContactPhone();
phone.Number = "4255550101";
phone.Kind = ContactPhoneKind.Mobile;
contact.Phones.Add(phone);

ContactStore store = await
    ContactManager.RequestStoreAsync(ContactStoreAccessType.AppContactsReadWrite);

ContactList contactList;

IReadOnlyList<ContactList> contactLists = await store.FindContactListsAsync();

if (0 == contactLists.Count)
    contactList = await store.CreateContactListAsync("TestContactList");
else
    contactList = contactLists[0];

await contactList.SaveContactAsync(contact);

使用標註來標記每個連絡人

以應用程式可執行的 (例如：視訊通話和傳訊) 動作 (作業) 清單，將每個連絡人加上標籤。

然後，將連絡人的識別碼，關聯到應用程式內部用來識別該使用者的識別碼。

ContactAnnotationStore annotationStore = await
   ContactManager.RequestAnnotationStoreAsync(ContactAnnotationStoreAccessType.AppAnnotationsReadWrite);

ContactAnnotationList annotationList;

IReadOnlyList<ContactAnnotationList> annotationLists = await annotationStore.FindAnnotationListsAsync();
if (0 == annotationLists.Count)
    annotationList = await annotationStore.CreateAnnotationListAsync();
else
    annotationList = annotationLists[0];

ContactAnnotation annotation = new ContactAnnotation();
annotation.ContactId = contact.Id;
annotation.RemoteId = "user22";

annotation.SupportedOperations = ContactAnnotationOperations.Message |
  ContactAnnotationOperations.AudioCall |
  ContactAnnotationOperations.VideoCall |
 ContactAnnotationOperations.ContactProfile;

await annotationList.TrySaveAnnotationAsync(annotation);

註冊每個作業

在您的套件資訊清單中，註冊標註中列出的每個作業。

將通訊協定處理常式新增至資訊清單的 Extensions 元素，藉此進行註冊。

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="ms-contact-profile">
      <uap:DisplayName>TestProfileApp</uap:DisplayName>
    </uap:Protocol>
  </uap:Extension>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="ms-ipmessaging">
      <uap:DisplayName>TestMsgApp</uap:DisplayName>
    </uap:Protocol>
  </uap:Extension>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="ms-voip-video">
      <uap:DisplayName>TestVideoApp</uap:DisplayName>
    </uap:Protocol>
  </uap:Extension>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="ms-voip-call">
      <uap:DisplayName>TestCallApp</uap:DisplayName>
    </uap:Protocol>
  </uap:Extension>
</Extensions>

您也可以在 Visual Studio 資訊清單設計工具的 [宣告] 索引標籤中，新增這些項目。

指令清單設計工具的 [宣告] 索引標籤

在連絡人卡片中的動作旁邊找到您的應用程式

開啟連絡人應用程式。您的應用程式會出現在您標註和套件資訊清單中指定的每個動作 (作業) 旁邊。

聯繫人卡片

如果使用者選擇以您的應用程式進行某個動作，則下次使用者開啟連絡人卡片時，此應用程式就會以該動作的預設應用程式出現。

在迷你連絡人卡片中的動作旁邊找到您的應用程式

在迷你連絡人卡片中，您的應用程式會出現在代表動作的索引標籤中。

迷你聯繫人卡片

郵件應用程式之類的應用程式會開啟迷你連絡人卡片。您的應用程式也可以開啟它們。這個程式碼將示範如何達成該目標。

public async void OpenContactCard(object sender, RoutedEventArgs e)
{
    // Get the selection rect of the button pressed to show contact card.
    FrameworkElement element = (FrameworkElement)sender;

    Windows.UI.Xaml.Media.GeneralTransform buttonTransform = element.TransformToVisual(null);
    Windows.Foundation.Point point = buttonTransform.TransformPoint(new Windows.Foundation.Point());
    Windows.Foundation.Rect rect =
        new Windows.Foundation.Rect(point, new Windows.Foundation.Size(element.ActualWidth, element.ActualHeight));

   // helper method to find a contact just for illustrative purposes.
    Contact contact = await findContact("contoso@contoso.com");

    ContactManager.ShowContactCard(contact, rect, Windows.UI.Popups.Placement.Default);

}

若要查看更多有關迷你連絡人卡片的範例，請參閱連絡人卡片範例。

就像連絡人卡片一樣，每個索引標籤都會記住使用者上次使用的應用程式，因此他們可輕鬆回到您的應用程式。

當使用者在連絡人卡片中選取您的應用程式時執行作業

覆寫 App.cs 檔案中的 Application.OnActivated 方法，並引領使用者來到您應用程式中的頁面。連絡人卡片整合範例會介紹一種達成該目標的方式。

在頁面的程式碼後置檔案中，覆寫 Page.OnNavigatedTo 方法。連絡人卡片會將作業名稱和使用者的識別碼傳遞給此方法。

若要啟動視訊或音訊通話，請參閱此範例： VoIP 範例。您會在 WIndows.ApplicationModel.Calls 命名空間中找到完整的 API。

若要加強傳訊功能，請參閱 Windows.ApplicationModel.Chat 命名空間。

您也可以啟動另一個應用程式。這就是此程式碼的作用。

protected override async void OnNavigatedTo(NavigationEventArgs e)
{
    base.OnNavigatedTo(e);

    var args = e.Parameter as ProtocolActivatedEventArgs;
    // Display the result of the protocol activation if we got here as a result of being activated for a protocol.

    if (args != null)
    {
        var options = new Windows.System.LauncherOptions();
        options.DisplayApplicationPicker = true;

        options.TargetApplicationPackageFamilyName = "ContosoApp";

        string launchString = args.uri.Scheme + ":" + args.uri.Query;
        var launchUri = new Uri(launchString);
        await Windows.System.Launcher.LaunchUriAsync(launchUri, options);
    }
}

args.uri.scheme 屬性包含作業的名稱，而 args.uri.Query 屬性則包含使用者的識別碼。

共用方式為