Guia de início rápido: Selecionando contatos do usuário
Idioma: HTML | XAML

Guia de início rápido: selecionando contatos do usuário (HTML)

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Por meio do namespace Windows.ApplicationModel.Contacts, você tem várias opções para selecionar contatos. Vamos mostrar, aqui, como selecionar um único contato ou vários deles e vamos mostrar também como configurar o seletor de contatos para recuperar somente as informações de contatos necessárias ao aplicativo.

Pré-requisitos

  • Recomendamos que você se familiarize com o Microsoft Visual Studio e com os modelos a ele associados.
  • Recomendamos que você se familiarize com JavaScript.

Configurar o seletor de contatos

Crie uma instância de Windows.ApplicationModel.Contacts.ContactPicker e a atribua a uma variável.


var picker = Windows.ApplicationModel.Contacts.ContactPicker();


Digitar um nome para o botão de confirmação

O botão de confirmação é o botão que o usuário pressiona para confirmar o contato selecionado. Defina o nome desse botão com Windows.ApplicationModel.Contacts.CommitButtonText.


picker.commitButtonText = "Select";


Definir o modo de seleção (opcional)

Por padrão, o seletor de contatos recupera todos os dados disponíveis para os contatos selecionados pelo usuário. A propriedade selectionMode permite configurar o seletor de contatos para recuperar somente os campos de dados necessários ao aplicativo. Esta é a maneira mais eficiente de usar o seletor de contatos, caso você precise apenas de um subconjunto dos dados de contato disponíveis.

Primeiro, defina a propriedade selectionMode como fields.


picker.selectionMode = Windows.ApplicationModel.Contacts.ContactSelectionMode.fields;


Depois, use a propriedade desiredFieldsWithContactFieldType para especificar os campos a serem recuperados pelo seletor de contatos. Este exemplo configura o seletor de contatos para recuperar endereços de email:


picker.desiredFieldsWithContactFieldType.append(Windows.ApplicationModel.Contacts.ContactFieldType.email);    


Iniciar o seletor

Agora, você pode iniciar o seletor. Use pickContactAsync se quiser que o usuário selecione apenas um contato. Para processar o contato selecionado pelo usuário, use done para chamar uma função para processar o contato retornado pelo seletor.


        picker.pickContactAsync().done(function (contact) {
            if (contact !== null) {
                // Create UI to display the contact information for the selected contact
                var contactElement = document.createElement("div");
                contactElement.className = "contact";

                // Display the name
                contactElement.appendChild(createTextElement("h3", contact.displayName));


Use pickContactsAsync se quiser que o usuário selecione um ou mais contatos. Para processar os contatos selecionados pelo usuário, use done para chamar uma função para processar o contato retornado pelo seletor.



        picker.pickContactsAsync().done(function (contacts) {
            if (contacts.length > 0) {
                // Display the selected contact names
                var output = "Selected contacts:\n";
                contacts.forEach(function (contact) {
                    output += contact.displayName + "\n";
                });


Exemplo completo (único contato)

Esse exemplo usa o seletor de contatos para recuperar nome, endereços de email, números de telefone e endereços de um único contato.


(function () {
    "use strict";
    var page = WinJS.UI.Pages.define("/html/scenarioSingle.html", {
        ready: function (element, options) {
            // Use element.querySelector() instead of document.getElementById() to ensure that the correct default.html page is targeted.
            element.querySelector("#open").addEventListener("click", pickContact, false);
        }
    });

    function pickContact() {
        // Clean scenario output
        WinJS.log && WinJS.log("", "sample", "status");

        // Create the picker
        var picker = new Windows.ApplicationModel.Contacts.ContactPicker();
        picker.commitButtonText = "Select";

        // Open the picker for the user to select a contact
        picker.pickContactAsync().done(function (contact) {
            if (contact !== null) {
                // Create UI to display the contact information for the selected contact
                var contactElement = document.createElement("div");
                contactElement.className = "contact";

                // Display the name
                contactElement.appendChild(createTextElement("h3", contact.displayName));

                // Add the different types of contact data
                if (contact.emails.length > 0) {
                    contactElement.appendChild(createTextElement("h4", "Emails:"));
                    contact.emails.forEach(function (email) {
                        switch (email.kind) {
                            case Windows.ApplicationModel.Contacts.ContactEmailKind.personal:
                                contactElement.appendChild(createTextElement("div", email.address + " (personal)"));
                                break;
                            case Windows.ApplicationModel.Contacts.ContactEmailKind.work:
                                contactElement.appendChild(createTextElement("div", email.address + " (work)"));
                                break;
                            case Windows.ApplicationModel.Contacts.ContactEmailKind.other:
                                contactElement.appendChild(createTextElement("div", email.address + " (other)"));
                                break;
                        }
                    });
                }
                
                if (contact.phones.length > 0) {
                    contactElement.appendChild(createTextElement("h4", "Phone Numbers:"));
                    contact.phones.forEach(function (phone) {
                        switch (phone.kind) {
                            case Windows.ApplicationModel.Contacts.ContactPhoneKind.home:
                                contactElement.appendChild(createTextElement("div", phone.number + " (home)" ));
                                break;
                            case Windows.ApplicationModel.Contacts.ContactPhoneKind.work:
                                contactElement.appendChild(createTextElement("div", phone.number + " (work)" ));
                                break;
                            case Windows.ApplicationModel.Contacts.ContactPhoneKind.mobile:
                                contactElement.appendChild(createTextElement("div", phone.number + " (mobile)" ));
                                break;
                            case Windows.ApplicationModel.Contacts.ContactPhoneKind.other:
                                contactElement.appendChild(createTextElement("div", phone.number + " (other)" ));
                                break;
                        }
                    });
                }

                if (contact.addresses.length > 0) {
                    contactElement.appendChild(createTextElement("h4", "Addresses:"));
                    contact.addresses.forEach(function (address) {
                        switch (address.kind) {
                            case Windows.ApplicationModel.Contacts.ContactAddressKind.home:
                                contactElement.appendChild(createTextElement("div", getUnstructuredAddress(address) + " (home)" ));
                                break;
                            case Windows.ApplicationModel.Contacts.ContactAddressKind.work:
                                contactElement.appendChild(createTextElement("div", getUnstructuredAddress(address) + " (work)"));
                                break;
                            case Windows.ApplicationModel.Contacts.ContactAddressKind.other:
                                contactElement.appendChild(createTextElement("div", getUnstructuredAddress(address) + " (other)"));
                                break;
                        }
                    });
                }

                // Add the contact element to the page
                document.getElementById("output").appendChild(contactElement);
            } else {
                // The picker was dismissed without selecting a contact
                WinJS.log && WinJS.log("No contact was selected", "sample", "status");
            }
        });
    }

    function createTextElement(tag, text) {
        var element = document.createElement(tag);
        element.className = "singleLineText";
        element.innerText = text;
        return element;
    }

    function getUnstructuredAddress(contactAddress) {
        var unstructuredAddress = contactAddress.streetAddress + ", " + contactAddress.locality + ", " + contactAddress.region + ", " + contactAddress.postalCode;
        return unstructuredAddress;
    }


})();


Exemplo completo (vários contatos)

Esse exemplo usa o seletor de contatos para recuperar vários contatos e então exibir os nomes de contatos.



(function () {
    "use strict";
    var page = WinJS.UI.Pages.define("/html/scenarioMultiple.html", {
        ready: function (element, options) {
            // Use element.querySelector() instead of document.getElementById() to ensure that the correct default.html page is targeted.
            element.querySelector("#open").addEventListener("click", pickContacts, false);
        }
    });

    function pickContacts() {
        // Clean scenario output
        WinJS.log && WinJS.log("", "sample", "status");

        // Create the picker
        var picker = new Windows.ApplicationModel.Contacts.ContactPicker();
        picker.commitButtonText = "Select";

        // Open the picker for the user to select contacts
        picker.pickContactsAsync().done(function (contacts) {
            if (contacts.length > 0) {
                // Display the selected contact names
                var output = "Selected contacts:\n";
                contacts.forEach(function (contact) {
                    output += contact.displayName + "\n";
                });
                WinJS.log && WinJS.log(output, "sample", "status");
            } else {
                // The picker was dismissed without selecting any contacts
                WinJS.log && WinJS.log("No contacts were selected", "sample", "status");
            }
        });
    }
})();


Resumo e próximas etapas

Agora, você já tem o entendimento básico de como usar o seletor de contatos para recuperar informações de contatos. Baixe o exemplo de aplicativo Seletor de Contatos da galeria de códigos para ver mais exemplos de como usar contatos e o seletor de contatos.

Tópicos relacionados

Exemplo de aplicativo de Seletor de Contatos

 

 

Mostrar:
© 2017 Microsoft