通过

跨设备人员 API

  • 项目

Windows 是第三方应用用于集成其顶级联系人的理想平台。 通过此集成，用户可以与各种人员体验的人员交互。 Windows 现在为第三方 WinUI 3、UWP 和其他应用 提供包标识 和 API 来存储其所有联系人。

重要

一些信息与预发布产品相关，在商业发行之前可能会发生实质性修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

注意

应用可以在Windows 更新设置中将其发布到 Windows 预览体验计划（Beta 频道）后立即试用此功能（有关详细信息，请参阅 Windows 预览体验计划入门）。

应用在 Windows 中存储其联系人后，用户将能够在 Windows 的 “共享 ”面板中看到这些联系人建议，以便与其顶级联系人无缝共享。 有关“共享”面板的详细信息，请参阅如何在 Windows 上的 文件资源管理器中共享文件。

为人员合同创建 UserDataAccount

首先创建用户数据帐户。 第三方应用创建 UserDataAccount UserDisplayName 需要作为 "com.microsoft.peoplecontract".

UserDataAccountStore udas =
    await UserDataAccountManager.RequestStoreAsync(UserDataAccountStoreAccessType.AppAccountsReadWrite);
UserDataAccount uda = await udas.CreateAccountAsync("com.microsoft.peoplecontract");

接下来，添加到 "com.microsoft.windows.system" 帐户的 ExplictReadAccessPackageFamilyNames 列表。 这将提供对 Windows 体验的第三方联系人的受限访问。

uda.ExplictReadAccessPackageFamilyNames.Add("com.microsoft.windows.system");
await uda.SaveAsync();

存储联系人

存储联系人的第一步是创建联系人列表。 为此，第三方应用必须在 Windows ContactStore 中为 a UserDataAccount 创建新的联系人列表。 应用可以选择保留联系人列表的默认 OtherAppReadAccess 访问类型，同时将其 None 设置为阻止其他应用访问这些联系人。 有关可用访问类型的完整列表，请参阅 ContactListOtherAppReadAccess 枚举。

ContactStore store = await ContactManager.RequestStoreAsync(ContactStoreAccessType.AppContactsReadWrite);
this.contactList = await store.CreateContactListAsync(contactListsName, uda.Id);
contactList.OtherAppReadAccess = ContactListOtherAppReadAccess.None;
await contactList.SaveAsync();

存储联系人时，第三方应用必须包括 Windows 体验为联系人提供支持所需的所有相关信息。

存储联系人时需要以下字段：

  • FirstName
  • RemoteId
  • DisplayPicture

以下字段是可选的：

  • LastName
  • Phones
  • Emails

此代码片段演示如何存储联系人：

foreach (var appContact in AppContacts)
{
  var cont = new Contact
  {
    FirstName = appContact.FirstName,
    LastName = appContact.LastName,
    RemoteId = appContact.Id,
    SourceDisplayPicture = RandomAccessStreamReference.CreateFromUri(new Uri(appContact.ProfilePicPath)),
    Phones = { new ContactPhone { Number = appContact.Phone } }
  };

  await this.contactList.SaveContactAsync(cont);
}

注意

联系人DisplayName的构造使用FirstName和 LastName。 如果未提供姓氏， DisplayName 则与为名字提供的字符串相同。

存储联系人的排名

可以为联系人存储排名的批注列表 UserDataAccount 。 应用可以通过向联系人添加批注来存储其顶级联系人的排名。 这些批注作为批注列表的一部分存储在联系人存储中。

ContactAnnotationStore annotationStore = await
    ContactManager.RequestAnnotationStoreAsync(ContactAnnotationStoreAccessType.AppAnnotationsReadWrite);
this.contactAnnotationList = await annotationStore.CreateAnnotationListAsync(uda.Id);

可以使用联系人上的批注来存储顶级联系人的排名。 排名作为 ProviderProperties 的一部分存储在联系人批注中。 应用必须设置联系人批注Share上的 SupportedOperations 作为排名。

foreach (var appContact in topAppContacts)
{
  Contact contact = await list.GetContactFromRemoteIdAsync(topAppContact.RemoteID);
  var annotation = new ContactAnnotation
  {
    ContactId = contact.Id,
    SupportedOperations = ContactAnnotationOperations.Share
  };
  annotation.ProviderProperties.Add("Rank", rank);
  await annotationsLst.TrySaveAnnotationAsync(annotation);
}

更新联系人排名

在更新存储在 Windows 中的联系人的排名时，应用可自由决定。 Windows 建议定期更新排名列表，以提供最佳用户体验。 每当需要更新排名列表时，都需要执行几个步骤。

  1. 删除 ContactAnnotationList。

    应用具有热门联系人的更新列表后，可以删除批注列表，并创建包含其顶部联系人的更新批注的新批注列表。

    await this.contactAnnotationList.DeleteAsync();

  2. 创建新的 ContactAnnotationList。 按照“联系人”部分的“存储排名”中的步骤为顶级联系人创建新的批注列表和存储排名。

另请参阅