Selektor kontaktów w internecie

Interfejs Contact Picker API umożliwia użytkownikom łatwe udostępnianie kontaktów z listy kontaktów.

Pete LePage

Czym jest interfejs Contact Picker API?

Korzystanie z interfejsu Contact Picker API

Interfejs Contact Picker API wymaga wywołania metody z parametrem opcji, który określa typy informacji kontaktowych, które chcesz uzyskać. Druga metoda informuje, jakie informacje dostarczy system bazowy.

Wykrywanie cech

Aby sprawdzić, czy interfejs Contact Picker API jest obsługiwany, użyj tego kodu:

const supported = ('contacts' in navigator && 'ContactsManager' in window);

Dodatkowo na Androidzie selektor kontaktów wymaga Androida M lub nowszego.

Otwieranie selektora kontaktów

Punktem wejściowym interfejsu Contact Picker API jest navigator.contacts.select(). Po wywołaniu zwraca obietnicę i wyświetla selektor kontaktów, umożliwiając użytkownikowi wybranie kontaktów, które chce udostępnić witrynie. Po wybraniu elementów do udostępnienia i kliknięciu Gotowe obietnica zostaje spełniona i zwraca tablicę kontaktów wybranych przez użytkownika.

Podczas wywoływania funkcji select() musisz podać tablicę właściwości, które chcesz zwrócić jako pierwszy parametr (dozwolone wartości to 'name', 'email', 'tel', 'address' lub 'icon'), a opcjonalnie, czy można wybrać wiele kontaktów jako drugi parametr.

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

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

Interfejs Contacts Picker API można wywołać tylko z bezpiecznego kontekstu przeglądania najwyższego poziomu. Podobnie jak inne zaawansowane interfejsy API wymaga on gestu użytkownika.

Wykrywanie dostępnych usług

Aby wykryć, które właściwości są dostępne, wywołaj funkcję navigator.contacts.getProperties(). Zwraca obietnicę, która jest spełniana z tablicą ciągów znaków wskazujących, które właściwości są dostępne. Na przykład: ['name', 'email', 'tel', 'address']. Możesz przekazywać te wartości do select().

Pamiętaj, że usługi nie zawsze są dostępne i mogą być dodawane nowe. W przyszłości inne platformy i źródła kontaktów mogą ograniczyć zakres udostępnianych usług.

Obsługa wyników

Interfejs Contact Picker API zwraca tablicę kontaktów, a każdy kontakt zawiera tablicę żądanych właściwości. Jeśli kontakt nie ma danych dotyczących żądanej właściwości lub użytkownik zrezygnuje z udostępniania określonej właściwości, interfejs API zwróci pustą tablicę. (W sekcji Kontrola użytkownika opisuję, jak użytkownik wybiera właściwości).

Jeśli na przykład witryna zażąda name, email i tel, a użytkownik wybierze 1 kontakt, który ma dane w polu nazwy, poda 2 numery telefonu, ale nie ma adresu e-mail, zwrócona odpowiedź będzie wyglądać tak:

[{
  "email": [],
  "name": ["Queen O'Hearts"],
  "tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

Zabezpieczenia i uprawnienia

Zespół Chrome zaprojektował i wdrożył interfejs Contact Picker API zgodnie z głównymi zasadami określonymi w artykule Kontrolowanie dostępu do zaawansowanych funkcji platformy internetowej, w tym kontrolą użytkownika, przejrzystością i ergonomią. Każdy z nich wyjaśnię.

Kontrola sprawowana przez użytkowników

Dostęp do kontaktów użytkowników jest możliwy za pomocą selektora, który można wywołać tylko za pomocą gestu użytkownika w bezpiecznym kontekście przeglądania najwyższego poziomu. Dzięki temu witryna nie może wyświetlać selektora podczas ładowania strony ani losowo wyświetlać selektora bez żadnego kontekstu.

Nie ma możliwości zbiorczego wybierania wszystkich kontaktów, więc użytkownicy są zachęcani do wybierania tylko tych kontaktów, które chcą udostępnić w danej witrynie. Użytkownicy mogą też kontrolować, które usługi są udostępniane witrynie, przełączając przycisk usługi u góry selektora.

Przejrzystość

Aby wyjaśnić, które dane kontaktowe są udostępniane, selektor zawsze wyświetla nazwę i ikonę kontaktu oraz wszystkie właściwości, o które poprosiła witryna. Jeśli na przykład witryna poprosi o name, email i tel, w selektorze zostaną wyświetlone wszystkie 3 usługi. Jeśli witryna żąda tylko tel, selektor będzie wyświetlać tylko imię i nazwisko oraz numery telefonów.

Długie naciśnięcie kontaktu spowoduje wyświetlenie wszystkich informacji, które zostaną udostępnione, jeśli wybierzesz ten kontakt. (Patrz obraz kontaktu z Kotem z Cheshire).

Brak trwałości uprawnień

Dostęp do kontaktów jest przyznawany na żądanie i nie jest trwały. Za każdym razem, gdy witryna chce uzyskać dostęp, musi wywołać metodę navigator.contacts.select() za pomocą gestu użytkownika, a użytkownik musi indywidualnie wybrać kontakty, które chce udostępnić witrynie.

Prześlij opinię

Zespół Chrome chce poznać Twoje wrażenia związane z korzystaniem z interfejsu Contact Picker API.

Masz problem z implementacją?

Czy w implementacji Chrome występuje błąd? Czy implementacja różni się od specyfikacji?

• Zgłoś błąd na stronie https://new.crbug.com. Podaj jak najwięcej szczegółów, proste instrukcje odtworzenia błędu i ustaw Komponenty na Blink>Contacts.

Planujesz korzystać z interfejsu API?

Czy planujesz używać interfejsu Contact Picker API? Twoje publiczne wsparcie pomaga zespołowi Chrome ustalać priorytety funkcji i pokazuje innym dostawcom przeglądarek, jak ważne jest ich wspieranie.

• Opisz, jak zamierzasz z niej korzystać, w wątku na forum WICG Discourse.
• Wyślij tweeta do @ChromiumDev z hasztagiem #ContactPicker i napisz, gdzie i jak korzystasz z tej funkcji.

Przydatne linki

• Wyjaśnienie publiczne
• Specyfikacja selektora kontaktów
• Wersja demonstracyjna Contact Picker API i źródło wersji demonstracyjnej Contact Picker API
• Błąd śledzenia
• Wpis na ChromeStatus.com
• Komponent Blink: Blink>Contacts

Dziękujemy

Ogromne podziękowania dla Finnura Thorarinssona i Rayana Kanso, którzy wdrażają tę funkcję, oraz Petera Beverloo, którego kod bezwstydnie ukradłem i przerobiłem na potrzeby demonstracji.

PS: Nazwy w selektorze kontaktów to postacie z Alicji w Krainie Czarów.