---
title: API Contacts
slug: Archive/B2G_OS/API/API_Contacts
tags:
  - API
  - B2G
  - Contact
  - Contacts
  - Firefox OS
  - Guide
translation_of: Archive/B2G_OS/API/Contacts_API
---
<p></p><div class="overheadIndicator nonStandard nonStandardHeader">
      <p><strong><span title="Cette API n'a pas été standardisée."><i class="icon-warning-sign"> </i></span> Non standard</strong><br>
      Cette fonctionnalité n'est pas en voie de standardisation au W3C, mais elle est supportée par la plateforme Firefox OS. Bien que son implémentation puisse changer dans le futur et qu'elle n'est pas largement supportée par les différents navigateurs, elle est utilisable pour du code dédié aux applications Firefox OS.</p>
      </div><p></p>

<p></p><div class="warning">
    <p style="text-align: center;">Cette API est disponible sur <a href="/fr/docs/Mozilla/Firefox_OS">Firefox OS</a> pour <a href="/fr/docs/Mozilla/Firefox_OS/Security/Application_security#App_Types">des applications privilégiées ou certifiées</a> seulement.</p>
</div><p></p>

<h2 id="Résumé">Résumé</h2>

<p>L'API Contacts fournit une interface simple pour gérer les contacts des utilisateurs enregistrés dans le carnet d'adresses du système. Un cas pratique typique de l'API Contacts est l'implémentation d'une application de gestion de carnet d'adresses.</p>

<div class="note">
<p><strong>Note :</strong> Comme les informations personnelles des contacts utilisateurs constituent des données sensibles, seules les applications certifiées et privilégiées sont autorisées à accéder à cette API. L'utilisation des <a href="/en-US/docs/WebAPI/Web_Activities" title="/en-US/docs/WebAPI/Web_Activities">Activités Web</a> pour déléguer les opérations sur les contacts est préconisée pour les autres applications.</p>
</div>

<h2 id="Gestion_des_contacts">Gestion des contacts</h2>

<p>Les contacts enregistrés dans le carnet d'adresses du système sont accessibles par l'intermédiaire de la propriété <a href="/fr/docs/Web/API/Window/navigator/mozContacts" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>navigator.mozContacts</code></a>, elle-même étant une instance de l'interface <a href="/fr/docs/Web/API/ContactManager" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>ContactManager</code></a>.</p>

<h3 id="Ajout_d'un_contact">Ajout d'un contact</h3>

<p>La création d'une nouvelle entrée dans le carnet d'adresses du système se fait en deux étapes :</p>

<ol>
 <li>Instanciez un nouvel objet <a href="/fr/docs/Web/API/MozContact" title="The MozContact interface is used to describe a single contact in the device's contact database."><code>mozContact</code></a> et remplissez toutes les propriétés nécéssaires. L'interface <a href="/fr/docs/Web/API/MozContact" title="The MozContact interface is used to describe a single contact in the device's contact database."><code>mozContact</code></a> définit toutes les propriétés possibles pour un contact donné. Ces propriétés sont essentiellement les mêmes que celles définies dans la spécification vCard 4.0, avec les exceptions suivantes :
  <ul>
   <li>L'attribut vCard N est divisé en cinq propriétés : <a href="/fr/docs/Web/API/MozContact/familyName" title="La propriété familyName est une liste de tous les noms de famille possibles utilisables pour le contact."><code>familyName</code></a>, <a href="/fr/docs/Web/API/MozContact/givenName" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>givenName</code></a>, <a href="/fr/docs/Web/API/MozContact/additionalName" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>additionalName</code></a>, <a href="/fr/docs/Web/API/MozContact/honorificPrefix" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>honorificPrefix</code></a>, <a href="/fr/docs/Web/API/MozContact/honorificSuffix" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>honorificSuffix</code></a></li>
   <li>L'attribut vCard FN a été renommé <a href="/fr/docs/Web/API/MozContact/name" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>name</code></a></li>
   <li>L'attribut vCard GENDER est divisé en deux propriétés : <a href="/fr/docs/Web/API/MozContact/sex" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>sex</code></a>, <a href="/fr/docs/Web/API/MozContact/genderIdentity" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>genderIdentity</code></a></li>
   <li>Faîtes attention : la plupart des propriétés sont des tableaux. Firefox v1.3 vérifie cela de manière bien plus stricte et par conséquent du code qui fonctionnait avec Firefox v1.2 peut ne plus s'exécuter avec Firefox v1.3 à cause de ça.</li>
  </ul>
 </li>
 <li>Utilisez la méthode <a href="/fr/docs/Web/API/ContactManager/save" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>ContactManager.save()</code></a> avec l'objet contact comme premier paramètre. La méthode renvoie un <a href="/fr/docs/Web/API/DOMRequest" title="Un objet DOMRequest représente une opération en cours. Il fournit des callbacks qui sont appelés quand l'operation est finit, ainsi qu'une reférence au résultat de l'opération. Une méthode DOM qui initie une opération se poursuivant au cours du temps, retounera un objet DOMRequest que vous pouvez surveiller pour connaitre le déroulement de l'opération"><code>DOMRequest</code></a> pour conserver une trace de la réussite ou de l'échec de l'opération d'enregistrement.</li>
</ol>

<pre class="brush: js">// première méthode : définir les propriétés directement
var person = new mozContact();
person.givenName  = ["John"];
person.familyName = ["Doe"];
person.nickname   = ["No kidding"];

// seconde méthode : utilisation d'un objet
var contactData = {
  givenName: ["John"],
  familyName: ["Doe"],
  nickname: ["No kidding"]
};

var person = new mozContact(contactData); // Firefox OS 1.3 prend un paramètre pour initialiser l'objet
if ("init" in person) {
  // Firefox OS 1.2 et précédents utilisent une méthode "init" pour initialiser l'objet
  person.init(contactData);
}

// enregistre le nouveau contact
var saving = navigator.mozContacts.save(person);

saving.onsuccess = function() {
  console.log('nouveau contact enregistré');
  // Cela actualise la personne telle qu'elle est enregistrée
  // Elle comporte son ID interne unique
  // Notez que saving.result est null ici
};

saving.onerror = function(err) {
  console.error(err);
};
</pre>

<h3 id="Recherche_d'un_contact">Recherche d'un contact</h3>

<p>Deux méthodes permettent de récupérer un contact depuis le carnet d'adresses du système :</p>

<ul>
 <li><a href="/fr/docs/Web/API/ContactManager/find" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>ContactManager.find()</code></a> pour obtenir une liste de contacts spécifique</li>
 <li><a href="/fr/docs/Web/API/ContactManager/getAll" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>ContactManager.getAll()</code></a> pour récupérer tous les contacts</li>
</ul>

<p>Les deux méthodes attendent un paramètre qui est un objet défiinissant les options de filtres et de tri. <a href="/fr/docs/Web/API/ContactManager/getAll" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>ContactManager.getAll</code></a> n'accepte que les options de tri. Ces dernières sont :</p>

<ul>
 <li><code>sortBy</code> : Une chaîne de caractères représentant le champ sur lequel les résultats de la recherche seront triés. Pour le moment, seuls givenName et familyName sont supportés.</li>
 <li><code>sortOrder </code>: Une chaîne de caractères qui indique le sens du tri des résultats. Les valeurs possibles sont <code>descending</code> (descendant) ou <code>ascending (ascendant)</code>.</li>
</ul>

<p>Et les options de filtre :</p>

<ul>
 <li><code>filterBy</code> : Un tableau de chaînes de caractères représentant tous les champs utilisés pour le filtrage.</li>
 <li><code>filterValue</code> : La valeur avec laquelle faire la comparaison.</li>
 <li><code>filterOp</code> : L'opérateur de comparaison du filtre à utiliser. Les valeurs possibles sont <code>equals</code> (égal à), <code>startsWith</code> (commence par), et <code>match</code> (correspond à), cette dernière étant spécifique aux numéros de téléphone.</li>
 <li><code>filterLimit </code>: Le nombre de contacts à récupérer avec la méthode <a href="/fr/docs/Web/API/ContactManager/find" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>find</code></a>.</li>
</ul>

<p><a href="/fr/docs/Web/API/ContactManager/find" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>find</code></a> renvoie un objet <a href="/fr/docs/Web/API/DOMRequest" title="Un objet DOMRequest représente une opération en cours. Il fournit des callbacks qui sont appelés quand l'operation est finit, ainsi qu'une reférence au résultat de l'opération. Une méthode DOM qui initie une opération se poursuivant au cours du temps, retounera un objet DOMRequest que vous pouvez surveiller pour connaitre le déroulement de l'opération"><code>DOMRequest</code></a> et <a href="/fr/docs/Web/API/ContactManager/getAll" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>getAll</code></a> retourne un objet <a href="/fr/docs/Web/API/DOMCursor" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>DOMCursor</code></a> pour connaître la réussite ou l'échec d'une recherche.</p>

<p>Si la recherche réussit, son résultat est disponible dans la propriété <a href="/fr/docs/Web/API/DOMRequest/result" title="Cette propriété fournit la valeur de résultat pour l'opération d'un DOMRequest."><code>DOMRequest.result</code></a>, soit dans un tableau d'objets <a href="/fr/docs/Web/API/MozContact" title="The MozContact interface is used to describe a single contact in the device's contact database."><code>mozContact</code></a> pour <a href="/fr/docs/Web/API/ContactManager/find" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>find</code></a>, soit dans un unique objet <a href="/fr/docs/Web/API/MozContact" title="The MozContact interface is used to describe a single contact in the device's contact database."><code>mozContact</code></a> pour <a href="/fr/docs/Web/API/ContactManager/getAll" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>getAll</code></a>. Pour obtenir le résultat suivant dans la liste obtenue avec <a href="/fr/docs/Web/API/ContactManager/getAll" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>getAll</code></a>, appelez la méthode <code>continue()</code> du curseur.</p>

<pre class="brush: js">var options = {
  filterValue : "John",
  filterBy    : ["givenName","name","nickName"],
  filterOp    : "contains",
  filterLimit : 1,
  sortBy      : "familyName",
  sortOrder   : "ascending"
}

var search = navigator.mozContacts.find(options);

search.onsuccess = function() {
  if (search.result.length === 1) {
    var person = search.result[0];
    console.log("Trouvé :" + person.givenName[0] + " " + person.familyName[0]);
  } else {
    console.log("Désolé, il n'y a pas de tel contact.")
  }
};

search.onerror = function() {
  console.warn("Aïe ! Quelque chose ne va pas, aucun résultat !");
};

var allContacts = navigator.mozContacts.getAll({sortBy: "familyName", sortOrder: "descending"});

allContacts.onsuccess = function(event) {
  var cursor = event.target;
  if (cursor.result) {
    console.log("Trouvé : " + cursor.result.givenName[0] + " " + cursor.result.familyName[0]);
    cursor.continue();
  } else {
    console.log("Pas d'autre contact");
  }
};

allContacts.onerror = function() {
  console.warn("Quelque chose s'est mal passée ! :(");
};
</pre>

<h3 id="Mise_à_jour_d'un_contact">Mise à jour d'un contact</h3>

<p>Lors de l'obtention d'un contact par l'intermédiaire de <a href="/fr/docs/Web/API/ContactManager/find" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>find()</code></a> ou de <a href="/fr/docs/Web/API/ContactManager/getAll" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>getAll()</code></a> (ou après un appel réussi à <a href="/fr/docs/Web/API/ContactManager/save" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>save()</code></a> pour un nouveau contact), celui-ci se voit attribuer des méta-données :</p>

<ul>
 <li>Un ID unique accessible via <a href="/fr/docs/Web/API/MozContact/id" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>mozContact.id</code></a></li>
 <li>Un objet <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date" title="/en-US/docs/JavaScript/Reference/Global_Objects/Date">Date</a> à l'intérieur de <a href="/fr/docs/Web/API/MozContact/updated" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>mozContact.updated</code></a> pour représenter la date de dernière modification du contact.</li>
</ul>

<p>Actualiser un contact revient globalement à modifier les valeurs de ses propriétés puis à l'enregistrer via un appel à la méthode <a href="/fr/docs/Web/API/ContactManager/save" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>save()</code></a>.</p>

<div class="note">
<p><strong>Note :</strong> À chaque fois qu'un contact est ajouté, mis à jour ou supprimé, un événement <code><a href="/fr/docs/Web/Reference/Events/contactchange" title="/fr/docs/Web/Reference/Events/contactchange">contactchange</a></code> est déclenché afin d'avoir un suivi de tous les changements apportés au carnet d'adresses du système. Cet événement peut être géré avec la propriété <a href="/fr/docs/Web/API/ContactManager/oncontactchange" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>ContactManager.oncontactchange</code></a>.</p>
</div>

<h3 id="Suppression_d'un_contact">Suppression d'un contact</h3>

<p>Un appel à la méthode <a href="/fr/docs/Web/API/ContactManager/remove" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>ContactManager.remove()</code></a> va tout simplement supprimer l'objet <a href="/fr/docs/Web/API/MozContact" title="The MozContact interface is used to describe a single contact in the device's contact database."><code>mozContact</code></a> qui lui a été transmis.</p>

<p>Dans certains cas limites, il est aussi possible de se débarrasser de tous les contacts. Pour cela, utilisez <a href="/fr/docs/Web/API/ContactManager/clear" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>ContactManager.clear()</code></a>. Soyez prudent lors de l'appel de cette méthode ; il n'est pas possible de revenir en arrière.</p>

<h2 id="Specifications" name="Specifications">Spécifications</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Spécification</th>
   <th scope="col">État</th>
   <th scope="col">Commentaire</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><a class="external" href="https://www.w3.org/2012/sysapps/contacts-manager-api/" hreflang="en" lang="en">Contacts Manager API<br><small lang="fr">La définition de 'Contacts Manager API' dans cette spécification.</small></a></td>
   <td><span class="spec-Obsolete">Obsolete</span></td>
   <td> </td>
  </tr>
  <tr>
   <td><a class="external" href="https://tools.ietf.org/html/rfc6350" hreflang="en" lang="en" title="La spécificaction 'vCard Format Specification'">vCard Format Specification</a></td>
   <td><span class="spec-RFC">IETF RFC</span></td>
   <td>RFC 6350</td>
  </tr>
 </tbody>
</table>

<h2 id="Compatibilité_des_navigateurs">Compatibilité des navigateurs</h2>

<p></p><p class="warning"><strong><a href="https://github.com/mdn/browser-compat-data">Nous convertissons les données de compatibilité dans un format JSON</a></strong>.
            Ce tableau de compatibilité utilise encore l'ancien format
            car nous n'avons pas encore converti les données qu'il contient.
            <strong><a href="/fr/docs/MDN/Contribute/Structures/Compatibility_tables">Vous pouvez nous aider en contribuant !</a></strong></p>

<div class="htab">
    <a id="AutoCompatibilityTable" name="AutoCompatibilityTable"></a>
    <ul>
        <li class="selected"><a>Ordinateur</a></li>
        <li><a>Mobile</a></li>
    </ul>
</div><p></p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Caractéristique</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>support basique</td>
   <td><span style="color: #f00;">Pas de support</span></td>
   <td><span style="color: #f00;">Pas de support</span></td>
   <td><span style="color: #f00;">Pas de support</span></td>
   <td><span style="color: #f00;">Pas de support</span></td>
   <td><span style="color: #f00;">Pas de support</span></td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Caractéristique</th>
   <th>Android</th>
   <th>Chrome pour Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>Firefox OS</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>basic support</td>
   <td><span style="color: #f00;">Pas de support</span></td>
   <td><span style="color: #f00;">Pas de support</span></td>
   <td>18.0</td>
   <td>1.1</td>
   <td><span style="color: #f00;">Pas de support</span></td>
   <td><span style="color: #f00;">Pas de support</span></td>
   <td><span style="color: #f00;">Pas de support</span></td>
  </tr>
 </tbody>
</table>
</div>

<h2 id="Voir_aussi">Voir aussi</h2>

<ul>
 <li><a href="/fr/docs/Web/API/Window/navigator/mozContacts" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>navigator.mozContacts</code></a></li>
 <li><a href="/fr/docs/Web/API/MozContact" title="The MozContact interface is used to describe a single contact in the device's contact database."><code>mozContact</code></a></li>
 <li><a href="/fr/docs/Web/API/ContactManager" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>ContactManager</code></a></li>
 <li><a href="/fr/docs/Web/API/MozContactChangeEvent" title="Cette documentation n'a pas encore été rédigée, vous pouvez aider en contribuant !"><code>MozContactChangeEvent</code></a></li>
 <li><a href="https://github.com/soapdog/firefoxos-sample-app-contact-exporter" title="Firefox OS Contact Exported Sample App">Application d'exemple pour exporter les contacts sous Firefox OS</a></li>
</ul>