Contacts

Contacts

El objeto contacts proporciona acceso a la agenda del dispositivo.

Métodos

Argumentos

Objetos


contacts.create

Retorna un objeto Contact nuevo.

var contact = navigator.contacts.create(properties);

Descripción

contacts.create es una función síncrona que retornara un objeto Contact nuevo.

Este método no hace el contacto persistente en la base de datos de contactos. Para hacerlo persistente, llama al método Contact.save.

Plataformas Soportadas

Ejemplo Rápido

var myContact = navigator.contacts.create({"displayName": "Usuario Prueba"});

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Contacts</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espere a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
        var myContact = navigator.contacts.create({"displayName": "Usuario Prueba"});
        myContact.gender = "male";
        console.log("El contacto, " + myContact.displayName + ", es de genero " + myContact.gender);
    }


    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Creación de Contactos</p>
  </body>
</html>

contacts.find

Consulta la base de datos de contactos y retorna uno o mas objetos Contact, cada uno con los campos especificados.

navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);

Descripción

contacts.find es una función asíncrona que consulta la base de datos de la agenda del dispositivo y retorna un array de objetos Contact. Los objetos retornados son pasados a la función 'callback' contactSuccess especificada en el argumento contactSuccess.

Los usuarios pueden especificar los campos que solicitan en la consulta con el argumento contactFields. Solo los campos que solicites en contactFields serán retornados como propiedades del objeto Contact, que a su vez es pasado a la función 'callback' contactSuccess. Si se entrega un array contactFields vacio, el objeto Contact retornada solo las propiedades id. El valor ["*"] en contactFields retornara todos los campos.

La string contactFindOptions.filter puede usarse como filtro cuando se consulte a la base de datos. Si se entrega, este valor es sensible a capitalización y a coincidencias parciales sobre cada campo que especificastes en el argumento contactFields. Si se encuentra una coincidencia con cualquier campo especificado, se retornara el contacto.

Argumentos

Plataformas Soportadas

Ejemplo Rápido

function onSuccess(contacts) {
    alert('Se encontró ' + contacts.length + ' contactos.');
};

function onError(contactError) {
    alert('onError!');
};

// Busca todos los contactos con 'Bob' en cualquier campo "name"
var options = new ContactFindOptions();
options.filter="Bob"; 
var fields = ["displayName", "name"];
navigator.contacts.find(fields, onSuccess, onError, options);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Contacts</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espera a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
        // Busca todos los contactos con 'Bob' en cualquier campo "name"
        var options = new ContactFindOptions();
        options.filter="Bob"; 
        var fields = ["displayName", "name"];
        navigator.contacts.find(fields, onSuccess, onError, options);
    }

    // onSuccess: Obtiene el resultado de los contactos actuales
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            console.log("Nombre a mostrar (DisplayName) = " + contacts[i].displayName);
        }
    }

    // onError: Fallo al obtener contactos
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Búsqueda de Contactos</p>
  </body>
</html>

Contact

Contiene propiedades que describen un contacto, como su información personal o de trabajo.

Atributos

Metodos

Detalles

El objeto Contact representa un contacto. Los contactos pueden ser creados, guardados o eliminados de la base de datos del dispositivo. También pueden ser retornados (Individualmente o en masa) llamando al método contacts.find.

Nota: No todos los campos de contactos están soportados en todas las plataformas. Comprueba las peculiaridades de cada plataforma para saber que campos están soportados.

Plataformas Soportadas

Ejemplo Rápido de Guardado

function onSuccess(contact) {
    alert("Se guardo satisfactoriamente");
};

function onError(contactError) {
    alert("Error = " + contactError.code);
};

// crea un nuevo objeto contacto
var contact = navigator.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber";       // especifica ambos para soportar todos los dispositivos

// Rellena varios campos
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;

// guarda en el dispositivo
contact.save(onSuccess,onError);

Ejemplo Rápido de Clonación

// Clona el objeto contacto
var clone = contact.clone();
clone.name.givenName = "John";
console.log("Nombre del contacto original = " + contact.name.givenName);
console.log("Nombre del contacto clonado = " + clone.name.givenName);

Ejemplo Rápido de eliminación

function onSuccess() {
    alert("Se elimino satisfactoriamente");
};

function onError(contactError) {
    alert("Error = " + contactError.code);
};

// elimina el contacto del dispositivo
contact.remove(onSuccess,onError);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Contacts</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espere a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
        // crea
        var contact = navigator.contacts.create();
        contact.displayName = "Plumber";
        contact.nickname = "Plumber";       //especifica ambos para soportar todos los dispositivos
        var name = new ContactName();
        name.givenName = "Jane";
        name.familyName = "Doe";
        contact.name = name;

        // guarda
        contact.save(onSaveSuccess,onSaveError);

        // clona
        var clone = contact.clone();
        clone.name.givenName = "John";
        console.log("Nombre del contacto original = " + contact.name.givenName);
        console.log("Nombre del contacto clonado = " + clone.name.givenName); 

        // elimina
        contact.remove(onRemoveSuccess,onRemoveError);
    }

    // onSaveSuccess: Obtiene el contacto guardado satisfactoriamente
    //
    function onSaveSuccess(contact) {
        alert("Se guardo satisfactoriamente");
    }

    // onSaveError: Fallo al guardar el contacto
    //
    function onSaveError(contactError) {
        alert("Error = " + contactError.code);
    }

    // onRemoveSuccess: Obtiene el contacto eliminado satisfactoriamente
    //
    function onRemoveSuccess(contacts) {
        alert("Eliminado satisfactoriamente");
    }

    // onRemoveError: Fallo al eliminar el contacto
    //
    function onRemoveError(contactError) {
        alert("Error = " + contactError.code);
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Búsqueda de Contactos</p>
  </body>
</html>

Peculiaridades Android 2.X

Peculiaridades Android 1.X

Peculiaridades BlackBerry WebWorks (OS 5.0 y superior)

Peculiaridades iOS


ContactAddress

Contiene propiedades de una de las direcciones de este contacto (Contact).

Propiedades

Detalles

El objeto ContactAddress almacena propiedades de un sola dirección del contacto. Un objeto Contact puede tener una o mas direcciones en el array ContactAddress[]

Plataformas Soportadas

Ejemplo Rápido

// Muestra información sobre la dirección de todos los contactos
function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        for (var j=0; j<contacts[i].addresses.length; j++) {
            alert("Preferente: " + contacts[i].addresses[j].pref + "\n" +
                    "Tipo: " + contacts[i].addresses[j].type + "\n" +
                    "Formateada: " + contacts[i].addresses[j].formatted + "\n" + 
                    "Dirección: "  + contacts[i].addresses[j].streetAddress + "\n" + 
                    "Localidad: "  + contacts[i].addresses[j].locality + "\n" + 
                    "Provincia: "  + contacts[i].addresses[j].region + "\n" + 
                    "Código Postal: "  + contacts[i].addresses[j].postalCode + "\n" + 
                    "País: "  + contacts[i].addresses[j].country);
        }
    }
};

function onError(contactError) {
    alert('onError!');
};

// Busca todos los contactos
var options = new ContactFindOptions();
options.filter=""; 
var filter = ["displayName","addresses"];
navigator.contacts.find(filter, onSuccess, onError, options);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Contacts</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espera a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
        // Busca todos los contactos
        var options = new ContactFindOptions();
        options.filter=""; 
        var filter = ["displayName","addresses"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Obtiene el resultado
    //
    function onSuccess(contacts) {
        // muestra la información de dirección de todos los contactos
        for (var i=0; i<contacts.length; i++) {
            for (var j=0; j<contacts[i].addresses.length; j++) {
                alert("Preferente: " + contacts[i].addresses[j].pref + "\n" +
                        "Tipo: " + contacts[i].addresses[j].type + "\n" +
                        "Formateada: " + contacts[i].addresses[j].formatted + "\n" + 
                        "Dirección: "  + contacts[i].addresses[j].streetAddress + "\n" + 
                        "Localidad: "  + contacts[i].addresses[j].locality + "\n" + 
                        "Provincia: "  + contacts[i].addresses[j].region + "\n" + 
                        "Código Postal: "  + contacts[i].addresses[j].postalCode + "\n" + 
                        "País: "  + contacts[i].addresses[j].country);
            }
        }
    };

    // onError: Ocurrió un error
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Búsqueda de Contactos</p>
  </body>
</html>

Peculiaridades Android 2.X

Peculiaridades Android 1.X

Peculiaridades BlackBerry WebWorks (OS 5.0 y superior)

Peculiaridades iOS


ContactField

Son campos genéricos de un objeto Contact. Algunas de las propiedades que se almacenan como objetos ContactField son: direcciones de email, números de teléfono, y urls.

Propiedades

Detalles

El objeto ContactField es un componente pensado para ser reusable. Cada objeto ContactField contiene una propiedad value, una type y una pref. Los objetos Contact almacenan varios objetos de este tipo en un array ContactField[], tales como números de teléfono o direcciones de emails.

En la mayoría de los casos no existen valores predeterminados para el atributo type. Por ejemplo, un numero de teléfono puede tener un valor type como 'home', 'work', 'mobile', 'iPhone' o cualquier otro, esto depende de la base de datos de la plataforma del dispositivo en cuestión. En cambio, en el caso del campo photos, PhoneGap hace uso del atributo type para indicar el formato de la imagen. PhoneGap retornara type: 'url' cuando cuando la propiedad value indique la URL al fichero de imagen, o type:'base64' cuando la imagen se retorne codificada como una string Base64.

Plataformas Soportadas

Ejemplo Rápido

// crea un nuevo contacto
var contact = navigator.contacts.create();

// almacena números de teléfonos en ContactField[]
var phoneNumbers = [3];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // numero preferente
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;

// guarda el contacto
contact.save();

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Contacts</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espera a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
        // crea un nuevo contacto
        var contact = navigator.contacts.create();

        // almacena números de teléfonos en ContactField[]
        var phoneNumbers = [3];
        phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
        phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // numero preferente
        phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
        contact.phoneNumbers = phoneNumbers;

        // guarda el contacto
        contact.save();

        // busca contactos, obtiene el nombre a mostrar y los números de teléfono.
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName","phoneNumbers"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Obtiene el resultado
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            // display phone numbers
            for (var j=0; j<contacts[i].phoneNumbers.length; j++) {
                alert("Type: " + contacts[i].phoneNumbers[j].type + "\n" + 
                        "Value: "  + contacts[i].phoneNumbers[j].value + "\n" + 
                        "Preferred: "  + contacts[i].phoneNumbers[j].pref);
            }
        }
    };

    // onError: Ocurrió un error
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Búsqueda de Contactos</p>
  </body>
</html>

Peculiaridades Android

Peculiaridades BlackBerry WebWorks (OS 5.0 y superior)

Peculiaridades iOS


ContactFindOptions

Contiene propiedades que se usan para filtrar el resultado de contacts.find.

Atributos

Plataformas Soportadas

Ejemplo Sencillo

// Función 'callback' de una búsqueda satisfactoria
function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        alert(contacts[i].displayName);
    }
};

// retrollamada (callback) de una búsqueda errónea
function onError(contactError) {
    alert('onError!');
};

// Indica criterios de búsqueda
var options = new ContactFindOptions();
options.filter="";          // una string vacía retorna todos los contactos
options.multiple=true;              // retornar mas de un contacto
filter = ["displayName"];           // retornar el campo contact.displayName

// Busca contactos
navigator.contacts.find(filter, onSuccess, onError, options);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Contacts</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espera a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
    // Indica un criterio de búsqueda
        var options = new ContactFindOptions();
        options.filter="";          // una string vacía retorna todos los contactos
        options.multiple=true;      // retornar mas de un contacto
        filter = ["displayName"];           // retornar el campo contact.displayName

    // Busca contactos
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Obtiene el resultado
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            alert(contacts[i].displayName);
        }
    };

    // onError: Ocurrió un error
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Búsqueda de Contactos</p>
  </body>
</html>

ContactName

Contiene atributos sobre nombres de un objeto Contact.

Atributos

Detalles

El objeto ContactName guarda atributos sobre el nombre de un contacto.

Plataformas Soportadas

Ejemplo Rápido

function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        alert("Nombre formateado: " + contacts[i].name.formatted + "\n" + 
                "Apellidos: "  + contacts[i].name.familyName + "\n" + 
                "Primer Nombre: "  + contacts[i].name.givenName + "\n" + 
                "Segundo Name: "  + contacts[i].name.middleName + "\n" + 
                "Sufijo del nombre: "  + contacts[i].name.honorificSuffix + "\n" + 
                "Prefijo del nombre: "  + contacts[i].name.honorificSuffix);
    }
};

function onError(contactError) {
    alert('onError!');
};

var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","name"];
navigator.contacts.find(filter, onSuccess, onError, options);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Contacts</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espera a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
    var options = new ContactFindOptions();
    options.filter="";
    filter = ["displayName","name"];
    navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Obtiene el resultado
    //
function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
        alert("Nombre formateado: " + contacts[i].name.formatted + "\n" + 
            "Apellidos: "  + contacts[i].name.familyName + "\n" + 
            "Primer Nombre: "  + contacts[i].name.givenName + "\n" + 
            "Segundo nombre: "  + contacts[i].name.middleName + "\n" + 
            "Sufijo del nombre: "  + contacts[i].name.honorificSuffix + "\n" + 
            "Prefijo del nombre: "  + contacts[i].name.honorificPrefix);
        }
    };

    // onError: Ocurrió un error
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Búsqueda de Contactos</p>
  </body>
</html>

Peculiaridades Android

Peculiaridades BlackBerry WebWorks (OS 5.0 y superior)

Peculiaridades iOS


ContactOrganization

Contiene atributos sobre la organización de un objeto Contact.

Atributos

Detalles

El objeto ContactOrganization almacena atributos sobre la organización. Un objeto Contact guarda uno o mas objetos ContactOrganization en un array.

Plataformas Soportadas

Ejemplo Rápido

function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        for (var j=0; j<contacts[i].organizations.length; j++) {
            alert("Preferente: " + contacts[i].organizations[j].pref + "\n" +
                    "Tipo: " + contacts[i].organizations[j].type + "\n" +
                    "Nombre: " + contacts[i].organizations[j].name + "\n" + 
                    "Departmento: "  + contacts[i].organizations[j].department + "\n" + 
                    "Titulo: "  + contacts[i].organizations[j].title);
        }
    }
};

function onError(contactError) {
    alert('onError!');
};

var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","organizations"];
navigator.contacts.find(filter, onSuccess, onError, options);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Contacts</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espera a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName","organizations"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Obtiene el resultado
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            for (var j=0; j<contacts[i].organizations.length; j++) {
                alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
                        "Type: " + contacts[i].organizations[j].type + "\n" +
                        "Name: " + contacts[i].organizations[j].name + "\n" + 
                        "Department: "  + contacts[i].organizations[j].department + "\n" + 
                        "Title: "  + contacts[i].organizations[j].title);
            }
        }
    };

    // onError: Ocurrió un error
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Búsqueda de Contactos</p>
  </body>
</html>

Peculiaridades Android 2.X

Peculiaridades Android 1.X

Peculiaridades BlackBerry WebWorks (OS 5.0 y superior)

Peculiaridades iOS


ContactError

Cuando un error ocurra, se pasara un objeto ContactError a la funcion 'callback' contactError.

Propiedades

Constantes

Descripción

Cuando ocurra un error, se disparara la funcion 'callback' ContactError pasándole como argumento un objeto contactError.


contactSuccess

Función 'callback' que proporciona un array de objetos Contact como resultado del método contacts.find.

function(contacts) {
    // hacer algo
}

Argumentos

Ejemplo

function contactSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        console.log("Nombre = " + contacts[i].displayName;
}

contactError

Función 'callback' de error para las funciones de contactos.

function(error) {
    // Maneja el error
}

contactFields

Argumento requerido para el método contacts.find. Úsalo para indicar que campos deberían incluirse en el objeto Contact que este método retorna.

["name", "phoneNumbers", "emails"]

contactFindOptions

Argumento opcional del método contacts.find. Usa este argumento para filtrar los contactos retornados de la base de datos de contactos.

{ 
filter: "",
multiple: true,
    };

Opciones