ContactsManager: метод select()

Метод select() интерфейса ContactsManager возвращает Promise, который при разрешении предоставляет пользователю выбор контактов, которые они хотят выбрать для совместного использования. Для разрешения Promise требуется жест пользователя.

properties

Массив strings, определяющий, какую информацию нужно извлечь из контакта. Допустимые значения следующие:

• 'name': Имя контакта.
• 'tel': Номер(а) телефона контакта.
• 'email': Электронный адрес контакта.
• 'address': Почтовый адрес контакта.
• 'icon': Аватар контакта.

options Необязательно

Доступные параметры:

multiple

Булево значение, позволяющее выбрать несколько контактов. По умолчанию false.

Возвращает Promise, который разрешается массивом объектов, содержащих контактную информацию. Каждый объект представляет собой отдельный контакт и может содержать следующие свойства:

address

Массив Array объектов ContactAddress, каждый из которых содержит подробности уникального физического адреса.

email

Массив строк, содержащих электронные адреса.

icon

Массив объектов Blob, содержащих изображения человека.

name

Массив строк, каждая из которых содержит уникальное имя человека.

tel

Массив строк, каждая из которых содержит уникальный номер телефона человека.

InvalidStateError DOMException

Возвращается, если контекст просмотра не является верхнеуровневым, если всплывающее окно выбора контактов отображает флажок, обозначающий уже существующее всплывающее окно выбора контактов, так как в любой момент времени может существовать только одно всплывающее окно, или если запуск всплывающего окна выбора контактов не удался.

SecurityError DOMException

Возвращается, если метод не инициирован активацией пользователя.

TypeError

Возвращается, если properties пусто или если ни одно из указанных свойств не поддерживается.

Временная активация требуется. Пользователь должен взаимодействовать со страницей или элементом пользовательского интерфейса, чтобы эта функция работала.

В следующем примере задается массив свойств, которые необходимо извлечь для каждого контакта, а также объект параметров для выбора нескольких контактов.

Затем определяется асинхронная функция, которая использует метод select() для представления пользователю интерфейса выбора контактов и обработки выбранных результатов. handleResults() - это функция, определенная разработчиком.

const props = ["name", "email", "tel", "address", "icon"];
const opts = { multiple: true };

async function getContacts() {
  try {
    const contacts = await navigator.contacts.select(props, opts);
    handleResults(contacts);
  } catch (ex) {
    // Handle any errors here.
  }
}

В следующем примере используется getProperties() для обеспечения того, чтобы передавались только поддерживаемые свойства. В противном случае select() может сгенерировать TypeError. handleResults() - это функция, определенная разработчиком.

const supportedProperties = await navigator.contacts.getProperties();

async function getContacts() {
  try {
    const contacts = await navigator.contacts.select(supportedProperties);
    handleResults(contacts);
  } catch (ex) {
    // Handle any errors here.
  }
}