Contacts

요약

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

연락처 관리

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

연락처 추가

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

1. 필요한 속성이 담긴 새로운 mozContact 객체와 필드 인스턴스를 만듭니다. mozContact 인터페이스는 추가할 연락처의 모든 가능한 속성을 정의하고 있습니다. 이 속성들은 대부분 아래에 나온 예외를 제외하고 vCard 4.0 명세의 내용과 거의 비슷합니다:
   • vCard N 속성은 다음 5개의 속성으로 나눠졌습니다: familyName, givenName, additionalName, honorificPrefix, honorificSuffix
   • vCard FN 속성은 name으로 이름이 변경되었습니다.
   • vCard GENDER 속성은 다음 2개의 속성으로 나눠졌습니다: sex, genderIdentity
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.find()를 사용합니다.
• 모든 연락처를 가져오기 위해서는 ContactManager.getAll()를 사용합니다.

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

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

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

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

find는 DOMRequest 객체를 반환하고 getAll는 DOMCursor 객체를 반환해서 검색의 성공 실패 여부를 확인할 수 있습니다.

검색이 성공적으로 완료되면 검색 결과는 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()로 성공적으로 저장한 후)로 연락처를 가져오면 이 연락처에는 몇가지 메타데이터가 붙습니다:

• mozContact.id로 사용할 수 있는 유일한 ID 값
• 마지막으로 연락처가 수정된 시각을 나타내는 mozContact.updated의 Date 객체

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

연락처 삭제

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

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

명세

브라우저 호환성

Gecko 안내

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

참고 자료

• navigator.mozContacts
• mozContact
• ContactManager
• MozContactChangeEvent