跨设备人员 API

2025-04-23

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

应用在 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 UserDataAccount 中为 a 创建新的联系人列表。应用可以选择保留联系人列表的默认 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);
}

注意

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

存储联系人的分级

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

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

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

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 建议定期更新排名列表，以提供最佳用户体验。每当需要更新排名列表时，都需要执行几个步骤。

删除 ContactAnnotationList。

应用程序获得顶级联系人的更新列表后，可以删除原有的批注列表，并创建一个包含更新的顶级联系人批注的新批注列表。
```
await this.contactAnnotationList.DeleteAsync();
```
创建新的 ContactAnnotationList。按照“存储联系人排名”部分中的步骤，创建一个新的批注列表，为你的顶级联系人存储排名。