chrome.permissions

Mô tả

Sử dụng API chrome.permissions để yêu cầu các quyền không bắt buộc đã khai báo tại thời gian chạy thay vì thời gian cài đặt, để người dùng hiểu lý do cần có các quyền đó và chỉ cấp những quyền cần thiết.

Khái niệm và cách sử dụng

Cảnh báo về quyền tồn tại để mô tả các chức năng mà API cấp, nhưng một số cảnh báo trong số này có thể không rõ ràng. Permissions API cho phép nhà phát triển giải thích cảnh báo về quyền và giới thiệu dần các tính năng mới để người dùng có thể làm quen với tiện ích mà không gặp rủi ro. Bằng cách này, người dùng có thể chỉ định mức độ truy cập mà họ sẵn sàng cấp và những tính năng mà họ muốn bật.

Ví dụ: chức năng cốt lõi của phần mở rộng quyền không bắt buộc đang ghi đè trang thẻ mới. Một tính năng đang hiển thị mục tiêu của người dùng trong ngày. Tính năng này chỉ yêu cầu quyền truy cập vào bộ nhớ và không đưa ra cảnh báo. Tiện ích này có một tính năng bổ sung mà người dùng có thể bật bằng cách nhấp vào nút sau:

Một nút tiện ích cho phép các tính năng bổ sung.

Để hiển thị các trang web hàng đầu của người dùng, bạn cần có quyền topSites. Quyền này có cảnh báo sau.

Cảnh báo về tiện ích cho API topSites

Triển khai các quyền không bắt buộc

Bước 1: Quyết định những quyền cần thiết và những quyền không bắt buộc

Một tiện ích có thể khai báo cả quyền bắt buộc và quyền không bắt buộc. Nhìn chung, bạn nên:

• Sử dụng các quyền bắt buộc khi cần thiết cho chức năng cơ bản của tiện ích.
• Sử dụng các quyền không bắt buộc khi cần thiết cho các tính năng không bắt buộc trong tiện ích.

Ưu điểm của các quyền bắt buộc:

• Ít lời nhắc hơn: Tiện ích có thể nhắc người dùng một lần để chấp nhận tất cả các quyền.
• Quá trình phát triển đơn giản hơn: Các quyền cần thiết được đảm bảo có sẵn.

Ưu điểm của các quyền không bắt buộc:

• Tăng cường bảo mật: Tiện ích chạy với ít quyền hơn vì người dùng chỉ bật các quyền cần thiết.
• Thông tin tốt hơn cho người dùng: Tiện ích có thể giải thích lý do cần có một quyền cụ thể khi người dùng bật tính năng có liên quan.
• Dễ dàng nâng cấp hơn: Khi bạn nâng cấp tiện ích, Chrome sẽ không tắt tiện ích đó cho người dùng nếu bản nâng cấp thêm các quyền không bắt buộc thay vì các quyền bắt buộc.

Bước 2: Khai báo các quyền không bắt buộc trong tệp kê khai

Khai báo các quyền không bắt buộc trong tệp kê khai tiện ích bằng khoá optional_permissions, sử dụng định dạng giống như trường quyền:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

Nếu bạn muốn yêu cầu các máy chủ lưu trữ mà bạn chỉ phát hiện được trong thời gian chạy, hãy thêm "https://*/*" vào trường optional_host_permissions của tiện ích. Điều này cho phép bạn chỉ định bất kỳ nguồn gốc nào trong "Permissions.origins" miễn là nguồn gốc đó có giao thức phù hợp.

Các quyền không được chỉ định là không bắt buộc

Bạn có thể chỉ định hầu hết các quyền đối với tiện ích Chrome là không bắt buộc, ngoại trừ các trường hợp ngoại lệ sau.

Quyền	Mô tả
"debugger"	API chrome.debugger đóng vai trò là phương thức truyền tải thay thế cho giao thức gỡ lỗi từ xa của Chrome.
"declarativeNetRequest"	Cấp cho tiện ích quyền truy cập vào API chrome.declarativeNetRequest.
"devtools"	Cho phép tiện ích mở rộng chức năng của Chrome DevTools.
"geolocation"	Cho phép tiện ích sử dụng API định vị địa lý HTML5.
"mdns"	Cấp cho tiện ích quyền truy cập vào API chrome.mdns.
"proxy"	Cấp cho tiện ích quyền truy cập vào API chrome.proxy để quản lý chế độ cài đặt proxy của Chrome.
"tts"	API chrome.tts phát tính năng chuyển văn bản sang lời nói (TTS) được tổng hợp.
"ttsEngine"	API chrome.ttsEngine triển khai công cụ chuyển văn bản sang lời nói (TTS) bằng một tiện ích.
"wallpaper"	Chỉ dành cho ChromeOS. Sử dụng API chrome.wallpaper để thay đổi hình nền ChromeOS.

Xem phần Khai báo quyền để biết thêm thông tin về các quyền hiện có và cảnh báo về các quyền đó.

Bước 3: Yêu cầu cấp quyền không bắt buộc

Yêu cầu cấp quyền trong một cử chỉ của người dùng bằng permissions.request():

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  chrome.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

Chrome sẽ nhắc người dùng nếu việc thêm quyền dẫn đến thông báo cảnh báo khác với thông báo mà người dùng đã thấy và chấp nhận. Ví dụ: mã trước đó có thể dẫn đến lời nhắc như sau:

Ví dụ về lời nhắc xác nhận quyền.

Bước 4: Kiểm tra các quyền hiện tại của tiện ích

Để kiểm tra xem tiện ích của bạn có một quyền hoặc tập hợp quyền cụ thể hay không, hãy sử dụng permission.contains():

chrome.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

Bước 5: Xoá quyền

Bạn nên xoá các quyền khi không cần đến nữa. Sau khi một quyền bị xoá, lệnh gọi permissions.request() thường sẽ thêm lại quyền đó mà không cần nhắc người dùng.

chrome.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

Loại

Permissions

Thuộc tính

• nguồn gốc

  string[] không bắt buộc

  Danh sách quyền của máy chủ, bao gồm cả những quyền được chỉ định trong khoá optional_permissions hoặc permissions trong tệp kê khai và những quyền được liên kết với Tập lệnh nội dung.

• quyền

  string[] không bắt buộc

  Danh sách các quyền được đặt tên (không bao gồm máy chủ lưu trữ hoặc nguồn gốc).

Phương thức

addHostAccessRequest()

Promise Đang chờ xử lýMV3 trở lên

chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

Thêm yêu cầu truy cập vào máy chủ lưu trữ. Yêu cầu sẽ chỉ được báo hiệu cho người dùng nếu tiện ích có thể được cấp quyền truy cập vào máy chủ trong yêu cầu. Yêu cầu sẽ được đặt lại khi điều hướng trên nhiều nguồn gốc. Khi được chấp nhận, cấp quyền truy cập liên tục vào nguồn gốc hàng đầu của trang web

Tham số

• request

  đối tượng

  • documentId

    chuỗi không bắt buộc

    Mã nhận dạng của tài liệu có thể hiển thị yêu cầu quyền truy cập của máy chủ lưu trữ. Phải là tài liệu cấp cao nhất trong một thẻ. Nếu được cung cấp, yêu cầu sẽ xuất hiện trên thẻ của tài liệu được chỉ định và bị xoá khi tài liệu chuyển đến một nguồn gốc mới. Việc thêm một yêu cầu mới sẽ ghi đè mọi yêu cầu hiện có cho tabId. Bạn phải chỉ định thuộc tính này hoặc tabId.

  • hình mở khóa

    chuỗi không bắt buộc

    Mẫu URL nơi có thể hiển thị các yêu cầu truy cập vào máy chủ lưu trữ. Nếu được cung cấp, các yêu cầu truy cập máy chủ sẽ chỉ xuất hiện trên những URL khớp với mẫu này.

  • tabId

    số không bắt buộc

    Mã nhận dạng của thẻ có thể hiển thị các yêu cầu truy cập máy chủ lưu trữ. Nếu được cung cấp, yêu cầu sẽ xuất hiện trên thẻ đã chỉ định và bị xoá khi thẻ điều hướng đến một nguồn gốc mới. Việc thêm một yêu cầu mới sẽ ghi đè yêu cầu hiện có cho documentId. Bạn phải chỉ định thuộc tính này hoặc documentId.

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  () => void

Giá trị trả về

• Promise<void>

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

contains()

Promise

chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

Kiểm tra xem tiện ích có các quyền đã chỉ định hay không.

Tham số

• quyền

  Quyền truy cập

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (result: boolean) => void

  • kết quả

    boolean

    Đúng nếu tiện ích có các quyền đã chỉ định. Nếu một nguồn gốc được chỉ định là cả quyền không bắt buộc và mẫu khớp tập lệnh nội dung, thì thao tác này sẽ trả về false trừ phi cả hai quyền đều được cấp.

Giá trị trả về

• Promise<boolean>

  Chrome 96 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getAll()

Promise

chrome.permissions.getAll(
  callback?: function,
)

Lấy tập hợp quyền hiện tại của tiện ích.

Tham số

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (permissions: Permissions) => void

  • quyền

    Quyền truy cập

    Các quyền đang hoạt động của tiện ích. Xin lưu ý rằng thuộc tính origins sẽ chứa các nguồn gốc đã cấp từ những nguồn gốc được chỉ định trong khoá permissions và optional_permissions trong tệp kê khai và những nguồn gốc được liên kết với Tập lệnh nội dung.

Giá trị trả về

• Promise<Quyền>

  Chrome 96 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

remove()

Promise

chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

Xoá quyền truy cập vào các quyền đã chỉ định. Nếu có vấn đề khi xoá các quyền, runtime.lastError sẽ được đặt.

Tham số

• quyền

  Quyền truy cập

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (removed: boolean) => void

  • đã xóa

    boolean

    Đúng nếu các quyền đã bị xoá.

Giá trị trả về

• Promise<boolean>

  Chrome 96 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

removeHostAccessRequest()

Promise Đang chờ xử lýMV3 trở lên

chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

Xoá yêu cầu truy cập của máy chủ, nếu có.

Tham số

• request

  đối tượng

  • documentId

    chuỗi không bắt buộc

    Mã nhận dạng của tài liệu mà yêu cầu quyền truy cập của máy chủ lưu trữ sẽ bị xoá. Phải là tài liệu cấp cao nhất trong một thẻ. Bạn phải chỉ định thuộc tính này hoặc tabId.

  • hình mở khóa

    chuỗi không bắt buộc

    Mẫu URL nơi yêu cầu truy cập của máy chủ sẽ bị xoá. Nếu được cung cấp, mẫu này phải khớp chính xác với mẫu của một yêu cầu truy cập máy chủ lưu trữ hiện có.

  • tabId

    số không bắt buộc

    Mã của thẻ mà yêu cầu truy cập của máy chủ sẽ bị xoá. Bạn phải chỉ định thuộc tính này hoặc documentId.

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  () => void

Giá trị trả về

• Promise<void>

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

request()

Promise

chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

Yêu cầu quyền truy cập vào các quyền đã chỉ định, hiển thị lời nhắc cho người dùng nếu cần. Các quyền này phải được xác định trong trường optional_permissions của tệp kê khai hoặc là các quyền bắt buộc mà người dùng đã từ chối cấp. Đường dẫn trên mẫu nguồn gốc sẽ bị bỏ qua. Bạn có thể yêu cầu các tập hợp con của quyền gốc không bắt buộc; ví dụ: nếu chỉ định *://*\/* trong phần optional_permissions của tệp kê khai, bạn có thể yêu cầu http://example.com/. Nếu có vấn đề khi yêu cầu cấp quyền, runtime.lastError sẽ được đặt.

Tham số

• quyền

  Quyền truy cập

• lệnh gọi lại

  hàm không bắt buộc

  Tham số callback có dạng như sau:

  (granted: boolean) => void

  • granted

    boolean

    Đúng nếu người dùng đã cấp các quyền được chỉ định.

Giá trị trả về

• Promise<boolean>

  Chrome 96 trở lên

  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

Sự kiện

onAdded

chrome.permissions.onAdded.addListener(
  callback: function,
)

Được kích hoạt khi tiện ích có được các quyền mới.

Tham số

• lệnh gọi lại

  hàm

  Tham số callback có dạng như sau:

  (permissions: Permissions) => void

  • quyền

    Quyền truy cập

onRemoved

chrome.permissions.onRemoved.addListener(
  callback: function,
)

Được kích hoạt khi quyền truy cập vào các quyền đã bị xoá khỏi tiện ích.

Tham số

• lệnh gọi lại

  hàm

  Tham số callback có dạng như sau:

  (permissions: Permissions) => void

  • quyền

    Quyền truy cập