Questo plugin definisce un oggetto globale navigator.contacts, che fornisce l'accesso al database di contatti del dispositivo.
Anche se l‘oggetto è associato con ambito globale del navigator, non è disponibile fino a dopo l’evento deviceready.
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log(navigator.contacts);
}
Avviso: raccolta e utilizzo dei dati di contatto solleva questioni di privacy importante. Politica sulla privacy dell‘app dovrebbe discutere come app utilizza i dati di contatto e se è condiviso con altre parti. Informazioni di contatto sono considerate sensibile perché rivela le persone con cui una persona comunica. Pertanto, oltre alla politica di privacy dell’app, è fortemente consigliabile fornendo un preavviso di just-in-time prima app accede o utilizza i dati di contatto, se il sistema operativo del dispositivo non farlo già. Tale comunicazione deve fornire le informazioni stesse notate sopra, oltre ad ottenere l‘autorizzazione (ad esempio, presentando scelte per OK e No grazie). Si noti che alcuni mercati app possono richiedere l’app per fornire un preavviso di just-in-time e ottenere l‘autorizzazione dell’utente prima di accedere ai dati di contatto. Un‘esperienza utente chiara e facile--capisce che circonda l’uso del contatto dati aiuta a evitare la confusione dell'utente e percepito un uso improprio dei dati di contatto. Per ulteriori informazioni, vedere la guida sulla Privacy.
Ciò richiede cordova 5.0 + (v 1.0.0 stabile corrente)
cordova plugin add cordova-plugin-contacts
Versioni precedenti di cordova comunque possono installare tramite l'id deprecato (stantio v0.2.16)
cordova plugin add org.apache.cordova.contacts
È anche possibile installare direttamente tramite url di repo (instabile)
cordova plugin add https://github.com/apache/cordova-plugin-contacts.git
Creare www/manifest.webapp come descritto nel Manifest Docs. Aggiungi permisions rilevanti. C‘è anche la necessità di modificare il tipo di webapp in “privilegiato” - Manifest Docs. AVVERTENZA: tutte le apps privilegiato applicare Content Security Policy che vieta script inline. Inizializzare l’applicazione in un altro modo.
"type": "privileged",
"permissions": {
"contacts": {
"access": "readwrite",
"description": "Describe why there is a need for such permission"
}
}
Prima del Windows 10: Eventuali contatti restituiti dai metodi trovare e pickContact sono readonly, quindi l'applicazione non può modificarli. Metodo find disponibile solo sui dispositivi Windows Phone 8.1.
Windows 10 e sopra: Contatti possono essere salvati e deposito di app locale contatti verranno salvate. Contatti possono anche essere eliminati.
Windows 8 contatti sono readonly. Tramite i contatti di Cordova API non sono queryable/ricerche, si dovrebbe informare l‘utente di scegliere un contatto come una chiamata a contacts.pickContact che aprirà l’app ‘Persone’ dove l‘utente deve scegliere un contatto. Eventuali contatti restituiti sono readonly, quindi l’applicazione non può modificarli.
Il metodo navigator.contacts.create è sincrono e restituisce un nuovo oggetto di Contact.
Questo metodo non mantiene l'oggetto contatto nel database contatti dispositivo, per cui è necessario richiamare il metodo Contact.save.
var myContact = navigator.contacts.create({"displayName": "Test User"});
Il metodo navigator.contacts.find in modo asincrono, esegue una query sul database di contatti del dispositivo e restituisce una matrice di oggetti Contact. Gli oggetti risultanti vengono passati alla funzione di callback contactSuccess specificata dal parametro contactSuccess.
Il parametro contactFields specifica i campi per essere utilizzato come un qualificatore di ricerca. Un parametro di lunghezza zero, contactFields non è valido e si traduce in ContactError.INVALID_ARGUMENT_ERROR. Un valore di contactFields di "*" ricerche campi tutti i contatti.
La stringa di contactFindOptions.filter può essere utilizzata come un filtro di ricerca quando una query sul database di contatti. Se fornito, una distinzione, corrispondenza parziale valore viene applicato a ogni campo specificato nel parametro contactFields. Se esiste una corrispondenza per qualsiasi dei campi specificati, viene restituito il contatto. Uso contactFindOptions.desiredFields parametro di controllo quale contattare la proprietà deve essere rispedito indietro.
contactFields: contattare campi da utilizzare come un qualificatore di ricerca. (DOMString[]) [Required]
contactSuccess: funzione di callback successo richiamato con la matrice di oggetti contatto restituiti dal database. [Required]
contactError: funzione di callback di errore, viene richiamato quando si verifica un errore. [Facoltativo]
contactFindOptions: opzioni per filtrare navigator.contacts di ricerca. [Optional]
I tasti sono:
filter: la stringa di ricerca utilizzata per trovare navigator.contacts. (DOMString) (Default: "")
multiple: determina se l'operazione di ricerca restituisce più navigator.contacts. (Boolean) (Default: false)
contatto oggetto solo caratteristiche valori per questi campi. (DOMString[]) [Optional]function onSuccess(contacts) {
alert('Found ' + contacts.length + ' contacts.');
};
function onError(contactError) {
alert('onError!');
};
// find all contacts with 'Bob' in any name field
var options = new ContactFindOptions();
options.filter = "Bob";
options.multiple = true;
options.desiredFields = [navigator.contacts.fieldType.id];
var fields = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name];
navigator.contacts.find(fields, onSuccess, onError, options);
__contactFields__non è supportato, verrà ignorato. findmetodo cercherà sempre di abbinare il nome, indirizzo email o numero di telefono di un contatto.Il metodo navigator.contacts.pickContact lancia il contatto selettore per selezionare un singolo contatto. L'oggetto risultante viene passato alla funzione di callback contactSuccess specificata dal parametro contactSuccess.
contactSuccess: funzione di callback di successo viene richiamato con il singolo oggetto di contatto. [Richiesto]
contactError: funzione di callback di errore, viene richiamato quando si verifica un errore. [Facoltativo]
navigator.contacts.pickContact(function(contact){
console.log('The following contact has been selected:' + JSON.stringify(contact));
},function(err){
console.log('Error: ' + err);
});
L'oggetto Contact rappresenta il contatto di un utente. Contatti possono essere creati, memorizzati o rimossi dal database di contatti dispositivo. Contatti possono anche essere estratto (singolarmente o in blocco) dal database richiamando il metodo navigator.contacts.find.
Nota: non tutti i campi di contatto sopra elencati sono supportati su ogni piattaforma del dispositivo. Consultare la sezione di stranezze su ogni piattaforma per dettagli.
ID: un identificatore univoco globale. (DOMString)
displayName: il nome di questo contatto, adatto per la visualizzazione a utenti finali. (DOMString)
nome: un oggetto che contiene tutti i componenti di un nome di persone. (ContactName)
Nickname: un nome informale con cui affrontare il contatto. (DOMString)
phoneNumbers: una matrice di numeri di telefono del contatto. (ContactField[])
email: una matrice di indirizzi di posta elettronica del contatto. (ContactField[])
indirizzi: una matrice di indirizzi di contatto. (ContactAddress[])
IMS: una matrice di indirizzi IM tutto il contatto. (ContactField[])
organizzazioni: una matrice di organizzazioni di tutto il contatto. (ContactOrganization[])
compleanno: il compleanno del contatto. (Data)
Nota: una nota sul contatto. (DOMString)
foto: una matrice di foto del contatto. (ContactField[])
categorie: matrice di tutte le categorie definite dall'utente connesso con il contatto. (ContactField[])
URL: matrice di pagine web connesso con il contatto. (ContactField[])
clone: restituisce una nuova Contact oggetto che è una copia completa dell'oggetto chiamante, con la id proprietà impostatanull.
rimuovere: rimuove il contatto dal database contatti dispositivo, altrimenti esegue un callback di errore con un ContactError oggetto.
Salva: salva un nuovo contatto nel database di contatti del dispositivo, o aggiorna un contatto esistente se esiste già un contatto con lo stesso id .
function onSuccess(contact) {
alert("Save Success");
};
function onError(contactError) {
alert("Error = " + contactError.code);
};
// create a new contact object
var contact = navigator.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber"; // specify both to support all devices
// populate some fields
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;
// save to device
contact.save(onSuccess,onError);
// clone the contact object
var clone = contact.clone();
clone.name.givenName = "John";
console.log("Original contact name = " + contact.name.givenName);
console.log("Cloned contact name = " + clone.name.givenName);
function onSuccess() {
alert("Removal Success");
};
function onError(contactError) {
alert("Error = " + contactError.code);
};
// remove the contact from the device
contact.remove(onSuccess,onError);
null.categorie: parzialmente supportati. Campi pref e tipo stanno tornandonull
IMS: non supportato
foto: non supportato
displayName: non supportata su iOS, tornando null se non c'è nessun ContactName specificato, nel qual caso restituisce il nome composito, soprannome o "" , rispettivamente.
compleanno: deve essere inserito come un JavaScript Date oggetto, allo stesso modo viene restituito.
foto: restituisce un URL del File dell‘immagine, che viene memorizzato nella directory temporanea dell’applicazione. Contenuto della directory temporanea vengono rimossi quando l'applicazione termina.
categorie: questa proprietà non è attualmente supportata, restituendonull.
displayName: quando si crea un contatto, il valore specificato per il parametro del nome di visualizzazione è diverso dal nome visualizzato Estratto quando trovare il contatto.
URL: quando si crea un contatto, gli utenti possono inserire e salvare più di un indirizzo web, ma solo uno è disponibile durante la ricerca del contatto.
phoneNumbers: non è supportata l‘opzione pref . Il tipo non è supportato in un’operazione di trovare . Un solo phoneNumber è consentita per ogni tipo.
email: non è supportata l'opzione pref . Home e personal fa riferimento la stessa voce di posta elettronica. È consentito un solo ingresso per ogni tipo.
indirizzi: supporta solo lavoro e casa/personali tipo. Il riferimento principale e personale tipo la stessa voce di indirizzo. È consentito un solo ingresso per ogni tipo.
organizzazioni: solo uno è consentito e non supporta gli attributi pref, tipoe dipartimento .
Nota: non supportato, restituendonull.
IMS: non supportato, restituendonull.
compleanni: non supportato, restituendonull.
categorie: non supportato, restituendonull.
remove: metodo non è supportato
foto: restituisce un URL del File dell‘immagine, che viene memorizzato nella directory temporanea dell’applicazione.
compleanni: non supportato, restituendonull.
categorie: non supportato, restituendonull.
remove: metodo è supportato solo in Windows 10 o superiore.
L'oggetto ContactAddress memorizza le proprietà di un singolo indirizzo di un contatto. Un oggetto Contact può includere più di un indirizzo in una matrice [] ContactAddress.
pref: impostare su true se questo ContactAddress contiene il valore dell'utente preferito. (booleano)
tipo: una stringa che indica il tipo di campo è, casa ad esempio. (DOMString)
formattato: indirizzo completo formattato per la visualizzazione. (DOMString)
streetAddress: l'indirizzo completo. (DOMString)
località: la città o località. (DOMString)
regione: lo stato o la regione. (DOMString)
postalCode: il codice postale o il codice postale. (DOMString)
paese: il nome del paese. (DOMString)
// display the address information for all contacts
function onSuccess(contacts) {
for (var i = 0; i < contacts.length; i++) {
for (var j = 0; j < contacts[i].addresses.length; j++) {
alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
"Type: " + contacts[i].addresses[j].type + "\n" +
"Formatted: " + contacts[i].addresses[j].formatted + "\n" +
"Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
"Locality: " + contacts[i].addresses[j].locality + "\n" +
"Region: " + contacts[i].addresses[j].region + "\n" +
"Postal Code: " + contacts[i].addresses[j].postalCode + "\n" +
"Country: " + contacts[i].addresses[j].country);
}
}
};
function onError(contactError) {
alert('onError!');
};
// find all contacts
var options = new ContactFindOptions();
options.filter = "";
var filter = ["displayName", "addresses"];
navigator.contacts.find(filter, onSuccess, onError, options);
false su dispositivi Android 2. x.pref: non è supportato sui dispositivi BlackBerry, restituendofalse.
tipo: parzialmente supportati. Solo uno di lavoro e casa tipo indirizzi può essere memorizzato per ciascun contatto.
formattato: parzialmente supportati. Restituisce una concatenazione di tutti i campi Indirizzo BlackBerry.
streetAddress: supportato. Restituisce una concatenazione di BlackBerry Indirizzo1 e Indirizzo2 campi indirizzo.
località: supportato. Memorizzato nel campo indirizzo città di BlackBerry.
regione: supportato. Memorizzato nel campo indirizzo di stateProvince BlackBerry.
postalCode: supportato. Memorizzato nel campo dell'indirizzo zipPostal BlackBerry.
paese: supportato.
pref: non è supportato sui dispositivi iOS, restituendofalse.
formattato: attualmente non supportati.
L‘oggetto ContactError viene restituito all’utente tramite la funzione di callback contactError quando si verifica un errore.
ContactError.UNKNOWN_ERROR (code 0)ContactError.INVALID_ARGUMENT_ERROR (code 1)ContactError.TIMEOUT_ERROR (code 2)ContactError.PENDING_OPERATION_ERROR (code 3)ContactError.IO_ERROR (code 4)ContactError.NOT_SUPPORTED_ERROR (code 5)ContactError.PERMISSION_DENIED_ERROR (code 20)L'oggetto ContactField è un componente riutilizzabile che rappresenta Contatta campi genericamente. Ogni oggetto ContactField contiene una proprietà di value, type e pref. Un oggetto Contact memorizza diverse proprietà in matrici [] ContactField, come numeri di telefono e indirizzi email.
Nella maggior parte dei casi, esistono pre-determinati valori per l‘attributo type di un oggetto ContactField. Ad esempio, un numero di telefono può specificare valori di type di casa, lavoro, mobile, iPhone o qualsiasi altro valore che è supportato dal database dei contatti su una piattaforma particolare dispositivo. Tuttavia, per il campo di photo del Contacto, il campo type indica il formato dell’immagine restituita: url quando il value di attributo contiene un URL per l'immagine fotografica, o base64, quando il value contiene una stringa con codifica base64 immagine.
tipo: una stringa che indica il tipo di campo è, casa ad esempio. (DOMString)
valore: il valore del campo, ad esempio un telefono numero o indirizzo e-mail. (DOMString)
pref: impostare su true se questo ContactField contiene il valore dell'utente preferito. (booleano)
// create a new contact
var contact = navigator.contacts.create();
// store contact phone numbers in ContactField[]
var phoneNumbers = [];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;
// save the contact
contact.save();
false.tipo: parzialmente supportati. Usato per i numeri di telefono.
valore: supportato.
pref: non supportato, restituendofalse.
false.false.false.Contiene diversi tipi di informazioni sul nome di un oggetto Contact.
formattato: il nome completo del contatto. (DOMString)
familyName: cognome del contatto. (DOMString)
givenName: nome del contatto. (DOMString)
middleName: il nome del contatto medio. (DOMString)
honorificPrefix: prefisso del contatto (esempio Mr o Dr) (DOMString)
honorificSuffix: suffisso del contatto (esempio Esq.). (DOMString)
function onSuccess(contacts) {
for (var i = 0; i < contacts.length; i++) {
alert("Formatted: " + contacts[i].name.formatted + "\n" +
"Family Name: " + contacts[i].name.familyName + "\n" +
"Given Name: " + contacts[i].name.givenName + "\n" +
"Middle Name: " + contacts[i].name.middleName + "\n" +
"Suffix: " + contacts[i].name.honorificSuffix + "\n" +
"Prefix: " + 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);
honorificPrefix , givenName , middleName , familyName , ehonorificSuffix.formattato: parzialmente supportati. Restituisce una concatenazione di campi firstName e lastName BlackBerry.
familyName: supportato. Archiviato in campo lastName BlackBerry.
givenName: supportato. Archiviato in campo firstName BlackBerry.
middleName: non supportato, restituendonull.
honorificPrefix: non supportato, restituendonull.
honorificSuffix: non supportato, restituendonull.
honorificPrefix , givenName , middleName , familyName , ehonorificSuffix.formattato: questo è l'unico nome proprietà ed è identico a displayName , enickname
familyName: non supportato
givenName: non supportato
middleName: non supportato
honorificPrefix: non supportato
honorificSuffix: non supportato
displayNameL'oggetto ContactOrganization memorizza la proprietà di organizzazione di un contatto. Un oggetto Contact memorizza uno o più oggetti ContactOrganization in una matrice.
pref: impostare su true se questo ContactOrganization contiene il valore dell'utente preferito. (booleano)
tipo: una stringa che indica il tipo di campo è, casa ad esempio. _(DOMString)
nome: il nome dell'organizzazione. (DOMString)
dipartimento: contratto lavora per il dipartimento. (DOMString)
titolo: titolo del contatto presso l'organizzazione. (DOMString)
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);
}
}
};
function onError(contactError) {
alert('onError!');
};
var options = new ContactFindOptions();
options.filter = "";
filter = ["displayName", "organizations"];
navigator.contacts.find(filter, onSuccess, onError, options);
false.pref: non supportato dai dispositivi BlackBerry, restituendofalse.
tipo: non supportato dai dispositivi BlackBerry, restituendonull.
nome: parzialmente supportati. Il primo nome dell'organizzazione è memorizzato nel campo azienda BlackBerry.
dipartimento: non supportato, restituendonull.
titolo: parzialmente supportati. Il primo titolo di organizzazione è memorizzato nel campo jobTitle BlackBerry.
pref: non supportato
tipo: non supportato
dipartimento: non supportato
Campi nome e titolo memorizzato in org e jobTitle.
pref: non è supportato sui dispositivi iOS, restituendofalse.
tipo: non è supportato sui dispositivi iOS, restituendonull.
nome: parzialmente supportati. Il primo nome dell'organizzazione è memorizzato nel campo kABPersonOrganizationProperty iOS.
dipartimento: parzialmente supportati. Il primo nome del dipartimento è memorizzato nel campo kABPersonDepartmentProperty iOS.
titolo: parzialmente supportati. Il primo titolo è memorizzato nel campo kABPersonJobTitleProperty iOS.
pref: non supportato, restituendofalse.
tipo: non supportato, restituendonull.