Trang này được dịch bởi Cloud Translation API.

Bộ chọn người liên hệ cho web

API Bộ chọn danh bạ cung cấp cho người dùng một cách thức dễ dàng để chia sẻ mục liên hệ từ danh bạ của họ.

Pete LePage

API Bộ chọn danh bạ là gì?

Quyền truy cập vào danh bạ của người dùng trên thiết bị di động đã là một tính năng trong các ứng dụng iOS/Android từ rất sớm. Đây là một trong những yêu cầu phổ biến nhất về tính năng mà tôi nhận được từ các nhà phát triển web và thường là lý do chính khiến họ tạo ứng dụng iOS/Android.

Có trong Chrome 80 trên Android M trở lên, quy cách API Bộ chọn liên hệ là một API theo yêu cầu cho phép người dùng chọn các mục trong danh bạ và chia sẻ thông tin chi tiết hạn chế về các mục đã chọn với trang web. Phương thức này cho phép người dùng chỉ chia sẻ những gì họ muốn vào thời điểm họ muốn, đồng thời giúp người dùng tiếp cận cũng như kết nối với bạn bè và gia đình dễ dàng hơn.

Ví dụ: ứng dụng email dựa trên nền tảng web có thể sử dụng API Bộ chọn danh bạ để chọn(những) người nhận email. Ứng dụng lồng tiếng IP có thể tra cứu số điện thoại cần gọi. Hoặc mạng xã hội có thể giúp người dùng biết được những người bạn nào đã tham gia.

Sử dụng API Bộ chọn danh bạ

API Bộ chọn danh bạ yêu cầu một lệnh gọi phương thức có tham số tuỳ chọn chỉ định loại thông tin liên hệ bạn muốn. Phương thức thứ hai cho bạn biết những thông tin mà hệ thống cơ bản sẽ cung cấp.

Phát hiện tính năng

Để kiểm tra xem API Bộ chọn danh bạ có được hỗ trợ hay không, hãy sử dụng:

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

Ngoài ra, trên Android, Công cụ chọn địa chỉ liên hệ yêu cầu Android M trở lên.

Mở Bộ chọn Địa chỉ Liên hệ

Điểm truy cập vào API Bộ chọn danh bạ là navigator.contacts.select(). Khi được gọi, phương thức này sẽ trả về một lời hứa và hiển thị bộ chọn người liên hệ, cho phép người dùng chọn(các) người liên hệ mà họ muốn chia sẻ với trang web. Sau khi chọn nội dung cần chia sẻ và nhấp vào Done (Xong), lời hứa sẽ phân giải bằng một mảng địa chỉ liên hệ do người dùng chọn.

Khi gọi select(), bạn phải cung cấp một mảng thuộc tính mà bạn muốn trả về làm tham số đầu tiên (với các giá trị được phép là bất kỳ giá trị nào trong số 'name', 'email', 'tel', 'address' hoặc 'icon') và tuỳ ý chọn xem có thể chọn nhiều người liên hệ làm tham số thứ hai hay không.

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.
}

Thận trọng: Để hỗ trợ 'address' và 'icon', bạn phải sử dụng Chrome 84 trở lên.

Bạn chỉ có thể gọi API Bộ chọn danh bạ từ ngữ cảnh duyệt web bảo mật, cấp cao nhất và giống như các API mạnh mẽ khác, API này yêu cầu cử chỉ của người dùng.

Phát hiện các cơ sở lưu trú hiện có

Để phát hiện xem thuộc tính nào đang có sẵn, hãy gọi navigator.contacts.getProperties(). Phương thức này trả về một lời hứa sẽ giải quyết bằng một mảng chuỗi cho biết thuộc tính nào có sẵn. Ví dụ: ['name', 'email', 'tel', 'address']. Bạn có thể chuyển các giá trị này đến select().

Hãy nhớ rằng các thuộc tính không phải lúc nào cũng có sẵn và các thuộc tính mới có thể được thêm vào. Trong tương lai, các nền tảng và nguồn liên hệ khác có thể hạn chế loại thuộc tính nào được chia sẻ.

Xử lý kết quả

API Bộ chọn địa chỉ liên hệ sẽ trả về một mảng địa chỉ liên hệ và mỗi địa chỉ liên hệ bao gồm một mảng các thuộc tính được yêu cầu. Nếu một người liên hệ không có dữ liệu cho thuộc tính được yêu cầu hoặc người dùng chọn không chia sẻ một thuộc tính cụ thể, thì API sẽ trả về một mảng trống. (Tôi mô tả cách người dùng chọn thuộc tính trong phần Kiểm soát của người dùng.)

Ví dụ: nếu một trang web yêu cầu name, email và tel và người dùng chọn một người liên hệ có dữ liệu trong trường tên, cung cấp 2 số điện thoại nhưng không có địa chỉ email, thì phản hồi được trả về sẽ là:

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

Tính bảo mật và quyền

Nhóm Chrome đã thiết kế và triển khai API Bộ chọn liên hệ theo các nguyên tắc cốt lõi được xác định trong Kiểm soát quyền truy cập vào các tính năng nền tảng web mạnh mẽ, bao gồm quyền kiểm soát của người dùng, độ trong suốt và hiệu quả. Tôi sẽ giải thích từng bước.

Quyền kiểm soát của người dùng

Quyền truy cập vào danh bạ của người dùng được cung cấp thông qua bộ chọn và chỉ có thể gọi bằng cử chỉ của người dùng, trên ngữ cảnh duyệt web cấp cao nhất, bảo mật. Điều này đảm bảo rằng một trang web không thể hiển thị bộ chọn khi tải trang hoặc hiển thị ngẫu nhiên bộ chọn mà không có bất kỳ ngữ cảnh nào.

Ảnh chụp màn hình, người dùng có thể chọn tài sản để chia sẻ. — Người dùng có thể chọn không chia sẻ một số tài sản. Trong ảnh chụp màn hình này, người dùng đã bỏ đánh dấu nút "Số điện thoại". Mặc dù trang web đã yêu cầu số điện thoại, nhưng những số này sẽ không được chia sẻ với trang web.

Không có lựa chọn nào để chọn hàng loạt tất cả thông tin liên hệ để người dùng chỉ được chọn những thông tin liên hệ mà họ cần chia sẻ cho trang web cụ thể đó. Người dùng cũng có thể kiểm soát thuộc tính nào được chia sẻ với trang web bằng cách bật/tắt nút thuộc tính ở đầu bộ chọn.

Sự minh bạch

Để làm rõ thông tin liên hệ nào đang được chia sẻ, bộ chọn luôn hiển thị tên và biểu tượng của người liên hệ cùng với mọi thuộc tính mà trang web đã yêu cầu. Ví dụ: nếu một trang web yêu cầu name, email và tel thì cả 3 thuộc tính sẽ xuất hiện trong bộ chọn. Ngoài ra, nếu một trang web chỉ yêu cầu tel, bộ chọn sẽ chỉ hiển thị tên và số điện thoại.

Ảnh chụp màn hình của bộ chọn cho trang web yêu cầu tất cả tài sản. — Bộ chọn, trang web yêu cầu `name`, `email` và `tel`, đã chọn một mục liên hệ.

Ảnh chụp màn hình bộ chọn cho trang web chỉ yêu cầu số điện thoại. — Bộ chọn, trang web chỉ yêu cầu `tel`, đã chọn một mục liên hệ.

Ảnh chụp màn hình bộ chọn khi nhấn và giữ một người liên hệ. — Kết quả của thao tác nhấn và giữ một người liên hệ.

Thao tác nhấn và giữ một người liên hệ sẽ hiển thị tất cả thông tin được chia sẻ nếu người liên hệ đó được chọn. (Xem hình ảnh liên hệ của Mèo Cheshire.)

Không có quyền cố định

Quyền truy cập vào danh bạ là theo yêu cầu và không được duy trì. Mỗi khi muốn có quyền truy cập, một trang web phải gọi navigator.contacts.select() bằng cử chỉ của người dùng và người dùng phải chọn riêng(các) người liên hệ mà họ muốn chia sẻ với trang web.

Ý kiến phản hồi

Nhóm Chrome muốn biết ý kiến của bạn về trải nghiệm với API Bộ chọn danh bạ.

Bạn gặp vấn đề khi triển khai?

Bạn có phát hiện thấy lỗi khi triển khai Chrome không? Hay cách triển khai có khác với thông số kỹ thuật không?

Báo cáo lỗi tại https://new.crbug.com. Hãy nhớ cung cấp nhiều chi tiết nhất có thể, cung cấp hướng dẫn đơn giản để tái tạo lỗi và đặt Thành phần thành Blink>Contacts. Tính năng nhiễu sóng rất hữu ích trong việc chia sẻ các bản mô phỏng vấn đề nhanh chóng và dễ dàng.

Bạn định sử dụng API?

Bạn có định sử dụng API Bộ chọn danh bạ không? Sự hỗ trợ công khai của bạn giúp nhóm Chrome ưu tiên các tính năng, đồng thời cho các nhà cung cấp trình duyệt khác biết tầm quan trọng của việc hỗ trợ họ.

Chia sẻ cách bạn dự định sử dụng tính năng này trên chuỗi bài đăng WICG Discourse.
Hãy gửi một dòng tweet đến @ChromiumDev kèm theo hashtag #ContactPicker và cho chúng tôi biết vị trí cũng như cách bạn sử dụng hashtag này.

Các đường liên kết hữu ích

Nội dung giải thích công khai
Quy cách Bộ chọn liên hệ
Bản minh hoạ API Bộ chọn liên hệ và Nguồn minh hoạ API Bộ chọn liên hệ
Theo dõi lỗi
Mục ChromeStatus.com
Thành phần nhấp nháy: Blink>Contacts

Cảm ơn bạn!

Xin chân thành cảm ơn Phần Lanur Thorarinsson và Rayan Kanso, những người đang triển khai tính năng này và Peter Beverloo, người đã mã Tôi xấu hổ ~~lấy cắp và~~ tái cấu trúc cho bản minh hoạ.

Tái bút: Tên trong công cụ chọn liên hệ của tôi là các nhân vật trong Alice ở xứ sở thần tiên.