選取連絡人

發行項
03/19/2024

透過 Windows.ApplicationModel.Contacts 命名空間，您有數個選項可供選取連絡人。在這裡，我們將示範如何選取單一連絡人或多個連絡人，而且我們將示範如何設定連絡人選擇器，只擷取應用程式所需的連絡人資訊。

設定連絡人選擇器

建立 Windows.ApplicationModel.Contacts.ContactPicker 的執行個體，並將它指派給變數。

var contactPicker = new Windows.ApplicationModel.Contacts.ContactPicker();

設定選取模式 (選擇性)

根據預設，連絡人選擇器會擷取使用者所選取連絡人的所有可用資料。 SelectionMode 屬性可讓您設定連絡人選擇器，只擷取應用程式所需的資料欄位。如果您只需要可用連絡人資料的子集，則以這個方式使用連絡人選擇器將更有效率。

首先，將 SelectionMode 屬性設定為 Fields：

contactPicker.SelectionMode = Windows.ApplicationModel.Contacts.ContactSelectionMode.Fields;

然後，使用 DesiredFieldsWithContactFieldType 屬性來指定您想要連絡人選擇器擷取的欄位。此範例設定讓連絡人選擇器擷取電子郵件地址：

contactPicker.DesiredFieldsWithContactFieldType.Add(Windows.ApplicationModel.Contacts.ContactFieldType.Email);

啟動選擇器

Contact contact = await contactPicker.PickContactAsync();

如果您想要讓使用者選取一個或多個連絡人，請使用 PickContactsAsync。

public IList<Contact> contacts;
contacts = await contactPicker.PickContactsAsync();

處理連絡人

當選擇器傳回時，檢查使用者是否已選取任何連絡人。如果是，則處理連絡人資訊。

此範例顯示如何處理單一連絡人。在這裡，我們會擷取連絡人的名稱，並將此資料複製到名為 OutputName 的 TextBlock 控制項中。

if (contact != null)
{
    OutputName.Text = contact.DisplayName;
}
else
{
    rootPage.NotifyUser("No contact was selected.", NotifyType.ErrorMessage);
}

此範例顯示如何處理多個連絡人。

if (contacts != null && contacts.Count > 0)
{
    foreach (Contact contact in contacts)
    {
        // Do something with the contact information.
    }
}

完整範例 (單一連絡人)

此範例會使用連絡人選擇器來擷取單一連絡人的名稱，以及電子郵件地址、位置或電話號碼。

// ...
using Windows.ApplicationModel.Contacts;
// ...

private async void PickAContactButton-Click(object sender, RoutedEventArgs e)
{
    ContactPicker contactPicker = new ContactPicker();

    contactPicker.DesiredFieldsWithContactFieldType.Add(ContactFieldType.Email);
    contactPicker.DesiredFieldsWithContactFieldType.Add(ContactFieldType.Address);
    contactPicker.DesiredFieldsWithContactFieldType.Add(ContactFieldType.PhoneNumber);

    Contact contact = await contactPicker.PickContactAsync();

    if (contact != null)
    {
        OutputFields.Visibility = Visibility.Visible;
        OutputEmpty.Visibility = Visibility.Collapsed;

        OutputName.Text = contact.DisplayName;

        AppendContactFieldValues(OutputEmails, contact.Emails);
        AppendContactFieldValues(OutputPhoneNumbers, contact.Phones);
        AppendContactFieldValues(OutputAddresses, contact.Addresses);
    }
    else
    {
        OutputEmpty.Visibility = Visibility.Visible;
        OutputFields.Visibility = Visibility.Collapsed;
    }
}

private void AppendContactFieldValues<T>(TextBlock content, IList<T> fields)
{
    if (fields.Count > 0)
    {
        StringBuilder output = new StringBuilder();

        if (fields[0].GetType() == typeof(ContactEmail))
        {
            foreach (ContactEmail email in fields as IList<ContactEmail>)
            {
                output.AppendFormat("Email: {0} ({1})\n", email.Address, email.Kind);
            }
        }
        else if (fields[0].GetType() == typeof(ContactPhone))
        {
            foreach (ContactPhone phone in fields as IList<ContactPhone>)
            {
                output.AppendFormat("Phone: {0} ({1})\n", phone.Number, phone.Kind);
            }
        }
        else if (fields[0].GetType() == typeof(ContactAddress))
        {
            List<String> addressParts = null;
            string unstructuredAddress = "";

            foreach (ContactAddress address in fields as IList<ContactAddress>)
            {
                addressParts = (new List<string> { address.StreetAddress, address.Locality, address.Region, address.PostalCode });
                unstructuredAddress = string.Join(", ", addressParts.FindAll(s => !string.IsNullOrEmpty(s)));
                output.AppendFormat("Address: {0} ({1})\n", unstructuredAddress, address.Kind);
            }
        }

        content.Visibility = Visibility.Visible;
        content.Text = output.ToString();
    }
    else
    {
        content.Visibility = Visibility.Collapsed;
    }
}

完整範例 (多個連絡人)

此範例會使用連絡人選擇器來擷取多個連絡人，然後將連絡人新增至名為 OutputContacts 的 ListView 控制項。

MainPage rootPage = MainPage.Current;
public IList<Contact> contacts;

private async void PickContactsButton-Click(object sender, RoutedEventArgs e)
{
    var contactPicker = new Windows.ApplicationModel.Contacts.ContactPicker();
    contactPicker.CommitButtonText = "Select";
    contacts = await contactPicker.PickContactsAsync();

    // Clear the ListView.
    OutputContacts.Items.Clear();

    if (contacts != null && contacts.Count > 0)
    {
        OutputContacts.Visibility = Windows.UI.Xaml.Visibility.Visible;
        OutputEmpty.Visibility = Visibility.Collapsed;

        foreach (Contact contact in contacts)
        {
            // Add the contacts to the ListView.
            OutputContacts.Items.Add(new ContactItemAdapter(contact));
        }
    }
    else
    {
        OutputEmpty.Visibility = Visibility.Visible;
    }         
}

public class ContactItemAdapter
{
    public string Name { get; private set; }
    public string SecondaryText { get; private set; }

    public ContactItemAdapter(Contact contact)
    {
        Name = contact.DisplayName;
        if (contact.Emails.Count > 0)
        {
            SecondaryText = contact.Emails[0].Address;
        }
        else if (contact.Phones.Count > 0)
        {
            SecondaryText = contact.Phones[0].Number;
        }
        else if (contact.Addresses.Count > 0)
        {
            List<string> addressParts = (new List<string> { contact.Addresses[0].StreetAddress,
              contact.Addresses[0].Locality, contact.Addresses[0].Region, contact.Addresses[0].PostalCode });
              string unstructuredAddress = string.Join(", ", addressParts.FindAll(s => !string.IsNullOrEmpty(s)));
            SecondaryText = unstructuredAddress;
        }
    }
}

摘要和後續步驟

您現在對於如何使用連絡人選擇器來擷取連絡人資訊，已具有基本的了解。從 GitHub 下載通用 Windows 應用程式範例，以查看更多使用連絡人和連絡人選擇器方式的相關範例。

共用方式為