Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Contacts

Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

This API is available on Firefox OS for privileged or certified applications only.

요약

주소록 API는 사용자 시스템의 주소록을 관리할 수 있는 간단한 인터페이스를 제공합니다. 주소록 API의 전형적인 사용 예는 주소록을 관리하는 어플리케이션을 제작하는 일입니다.

주의: 사용자의 연락처와 같은 개인 정보는 민감한 자료이기 때문에 권한 앱이나 인증입만이 이 API에 직접 접근할 수 있습니다. 다른 어플리케이션은 Web Activities를 사용해서 연락처에 접근하는 작업을 수행하게 하는 일을 권장합니다.

연락처 관리

시스템의 주소록에 저장된 연락처는 navigator.mozContacts 속성을 통해서 접근할 수 있습니다. 이 속성은 ContactManager 인터페이스의 인스턴스입니다.

연락처 추가

시스템의 주소록에 새로운 항목을 추가하는 일은 두가지 단계를 거칩니다:

  1. 필요한 속성이 담긴 새로운 mozContact 객체와 필드 인스턴스를 만듭니다. mozContact 인터페이스는 추가할 연락처의 모든 가능한 속성을 정의하고 있습니다. 이 속성들은 대부분 아래에 나온 예외를 제외하고 vCard 4.0 명세의 내용과 거의 비슷합니다:
  2. 연락처 객체를 첫번째 파라메터로 해서 ContactManager.save() 메서드를 사용합니다. 이 메서드는 DOMRequest를 반환해서 성공 여부를 확인할 수 있게 해줍니다.
var person = new mozContact();
person.givenName  = ["John"];
person.familyName = ["Doe"];
person.nickName   = ["No kidding"];

var saving = navigator.mozContacts.save(person);

saving.onsuccess = function() {
  console.log('new contact saved');
  // This update the person as it is stored
  // It includes its internal unique ID
  // Note that saving.result is null here
};

saving.onerror = function(err) {
  console.error(err);
};

연락처 찾기

시스템의 주소록에서 연락처를 가져오는 두개의 메서드가 있습니다:

두 메서드는 필터와 정렬 옵션을 정의하는 객체를 파라메터로 사용합니다. ContactManager.getAll은 정렬 옵션만을 사용합니다. 이 옵션은 다음과 같습니다:

  • sortBy: 검색 결과가 정렬될 필드를 나타내는 문자열입니다. 현재는 givenName과 familyName 만 지원합니다.
  • sortOrder: 결과의 정렬 순서를 나타내는 문자열입니다. descendingascending을 사용할 수 있습니다.

필터 옵션은 다음과 같습니다:

  • filterBy: 필터가 적용될 필드를 나타내는 문자열의 배열입니다.
  • filterValue: 대조할 값을 나타냅니다.
  • filterOp: 사용할 필터 비교 연산입니다. 가능한 값으로는 equals, startsWith, match가 있습니다. 후자는 특정 전화번호를 나타냅니다.
  • filterLimit: find 메서드로 가져올 연락처의 갯수입니다.

findDOMRequest 객체를 반환하고 getAllDOMCursor 객체를 반환해서 검색의 성공 실패 여부를 확인할 수 있습니다.

검색이 성공적으로 완료되면 검색 결과는 DOMRequest.result 속성을 통해서 사용할 수 있고 find의 경우에는 mozContact 객체의 배열이, getAll의 경우에는 하나의 mozContact 객체가 반환됩니다. getAll에서 다음 결과를 사용하려면 커서의 continue() 메서드를 사용합니다.

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("Found:" + person.givenName[0] + " " + person.familyName[0]);
  } else {
    console.log("Sorry, there is no such contact.")
  }
}

search.onerror = function() {
  console.warn("Uh! Something goes wrong, no result found!");
}

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

allContacts.onsuccess = function(event) {
  var cursor = event.target;
  if (cursor.result) {
    console.log("Found: " + cursor.result.givenName[0] + " " + cursor.result.familyName[0]);
    cursor.continue();
  } else {
    console.log("No more contacts");
  }
}

allContacts.onerror = function() {
  console.warn("Something went terribly wrong! :(");
}

연락처 수정

find()getAll()(또는 새 연락처를 save()로 성공적으로 저장한 후)로 연락처를 가져오면 이 연락처에는 몇가지 메타데이터가 붙습니다:

연락처를 수정하기 위해서는 속성값을 변경한 다음에 save() 메서드를 사용해서 저장하면 됩니다.

주의: 연락처가 추가되거나 수정, 삭제되면 contactchange 이벤트가 발생하고 이를 통해 시스템 주소록의 변경사항을 추적할 수 있습니다. 이 이벤트는 ContactManager.oncontactchange 속성을 이용해서 다룰 수 있습니다.

연락처 삭제

ContactManager.remove() 메서드를 사용해서 간단하게 전달된 mozContact 객체를 삭제할 수 있습니다.

특수한 경우에는 모든 연락처 정보를 삭제할 수도 있습니다. ContactManager.clear()를 사용하면 됩니다. 이 메서드를 사용할 때에는 특히 주의해야 합니다. 다시 되돌릴 수 있는 방법이 없습니다.

명세

Specification Status Comment
Contacts Manager API Working Draft First Working Draft (unstable)
vCard Format Specification RFC RFC6350

브라우저 호환성

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
basic support Not supported Not supported Not supported Not supported Not supported
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
basic support Not supported Not supported 18.0 Not supported Not supported Not supported

Gecko 안내

명세가 안정화되지 않았기 때문에 Gecko 구현은 비표준입니다.

참고 자료

문서 태그 및 공헌자

 이 페이지의 공헌자: hyeonseok
 최종 변경: hyeonseok,