Windows 用戶

Windows 是適合第三方應用程式整合其頂級人員聯繫人的理想平臺。這項整合可讓用戶與不同角色的體驗進行互動。 Windows 現在提供第三方 WinUI 和其他應用程式的套件身份，並透過 API 來儲存所有聯絡人。

一旦您的應用程式將聯繫人儲存在 Windows 中，使用者就能夠在 Windows 中的 [共用 ] 面板上看到這些聯繫人建議，以順暢地與其最上層聯繫人共用。如需共用面板的詳細資訊，請參閱如何在 Windows 上檔案總管共用檔案。

建立用於 People 合約的使用者資料帳戶

從建立用戶帳戶開始。需要第三方應用程式來建立 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 中建立的新聯繫人清單。應用程式可以選擇保留聯繫人清單的預設 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 中。除了排名之外，應用程式必須將 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。請遵循 [儲存聯繫人的排名] 區段中的步驟，為您的最上層聯繫人建立新的批注清單和儲存排名。

排名最佳實務

為了最大化你應用程式聯絡人在分享名單建議欄中的相關性，請遵循以下排名原則：

依新近性與頻率排序

排名可由以下組合計算：

最近互動時間：使用者上次與各聯絡人互動的時間
頻率：使用者與每個聯絡人互動的頻率

例如，昨天傳訊息的聯絡人排名可能是 95，而兩週前傳訊息的聯絡人可能有 60 排名。

// lastInteraction and interactionCount come from your app's own interaction
// telemetry. The Windows Contact class does not expose interaction history.
private int CalculateRank(DateTime lastInteraction, int interactionCount)
{
    TimeSpan daysSinceLastInteraction = DateTime.Now - lastInteraction;
    int frequencyScore = interactionCount * 10; // Max ~100
    int recencyScore = Math.Max(0, 100 - (daysSinceLastInteraction.Days * 3));

    return (recencyScore + frequencyScore) / 2;
}

移除過期的聯絡人

用戶30+天內未互動的聯絡人應該被移除或大幅降級。這讓建議保持新鮮且相關性：

private async Task PruneStaleContactsAsync()
{
    var now = DateTime.Now;
    var staleCutoff = now.AddDays(-30);
    
    foreach (var contact in this.AllTrackedContacts)
    {
        if (contact.LastInteractionDate < staleCutoff)
        {
            // Remove the annotation or set rank to 0
            var annotation = await GetAnnotationForContactAsync(contact);
            if (annotation != null)
            {
                annotation.ProviderProperties["Rank"] = 0;
                await this.contactAnnotationList.TrySaveAnnotationAsync(annotation);
            }
        }
    }
}

定期更新排名

依照你的應用程式安排排名更新的節奏——訊息應用程式是每日更新，電子郵件是每週更新，行事曆應用程式則是每月更新。必要時使用背景任務：

// Example: Update ranks when the app comes to foreground or on a timer
private async void UpdateRanksOnAppActivated()
{
    var topContacts = GetTopContactsByRecentActivity(50);
    await UpdateAnnotationRanksAsync(topContacts);
}

只提供明確的聯絡方式

你的應用程式應該只貢獻使用者明確新增或授權的聯絡人。絕不：

上傳整個通訊錄
未經使用者同意自動同步聯絡人
未經明確許可，分享公司目錄的聯絡資料

在將聯絡人儲存在 People 系統前，請先取得許可：

private async Task<bool> RequestContactStoreAccessAsync()
{
    // Requesting a writable ContactStore prompts the user for consent.
    // Your app must declare the contacts capability in its manifest.
    ContactStore store = await ContactManager.RequestStoreAsync(
        ContactStoreAccessType.AppContactsReadWrite);
    return store != null;
}

尊重使用者隱私設定

讓使用者能夠：

選擇要與 Windows 共享哪些聯絡人
選擇退出 People 整合
隨時從 Windows 刪除他們的聯絡人

// Provide a setting to disable sync
if (this.ShouldSyncContactsWithWindows)
{
    await SyncContactsAsync();
}
else
{
    // Clear contacts if the user disables sync
    await ClearWindowsContactsAsync();
}

當你依照上述指引排名並維護聯絡人時，使用者會在 Windows 分享表的建議欄看到你應用程式的熱門聯絡人。此路徑目前支援 People 聯絡人。

為確保您的聯絡人顯示：

使用DisplayName = "com.microsoft.peoplecontract"建立UserDataAccount
儲存包含必填欄位（FirstName、RemoteId、DisplayPicture）的聯絡人
建立含有階級的 ContactAnnotationList
在每個註解上設定SupportedOperations = Share
更新會根據更新頻率和頻率定期排序
30+天後修剪陳舊的隱形眼鏡

請參閱「從你的應用程式分享內容」和「在你的應用程式中接收內容」，以了解完整的分享工作表整合指南。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-06-23