Chrome hiện hỗ trợ không gian tên browser.* được chuẩn hoá (có từ Chrome 148). Chúng tôi đang dần cập nhật tài liệu. Hãy đọc thêm trong hướng dẫn chuyển đổi của chúng tôi.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

browser.permissions

Mô tả

Sử dụng API chrome.permissions để yêu cầu quyền không bắt buộc đã khai báo trong thời gian chạy thay vì thời gian cài đặt, để người dùng hiểu lý do cần 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 do API cấp, nhưng một số cảnh báo này có thể không rõ ràng. Permissions API cho phép nhà phát triển giải thích các cảnh báo về quyền và dần dần giới thiệu các tính năng mới, giúp người dùng 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 họ muốn bật.

Ví dụ: chức năng cốt lõi của tiện ích quyền không bắt buộc là ghi đè trang thẻ mới. Một tính năng là hiển thị mục tiêu trong ngày của người dùng. Tính năng này chỉ yêu cầu quyền bộ nhớ, không bao gồm 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:

Nút tiện ích cho phép sử dụng các tính năng bổ sung. — Nút tiện ích giúp bật 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. — 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 quyền nào là bắt buộc và quyền nào là 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 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 cho các tính năng không bắt buộc trong tiện ích của bạn.

Ưu điểm của 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.
Phát triển đơn giản hơn: Đảm bảo có các quyền cần thiết.

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

Bảo mật tốt hơn: 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 rõ ràng hơn cho người dùng: Tiện ích có thể giải thích lý do cần một quyền cụ thể khi người dùng bật tính năng liên quan.
Nâng cấp dễ dàng 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 manifest của tiện ích bằng khoá optional_permissions, sử dụng cùng định dạng với trường permissions:

{
  "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ủ mà bạn chỉ khám phá 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ó lược đồ phù hợp.

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

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

Quyền	Mô tả
`"debugger"`	API browser.debugger đóng vai trò là một 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 browser.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 vị trí địa lý HTML5.
`"mdns"`	Cấp cho tiện ích quyền truy cập vào API browser.mdns.
`"proxy"`	Cấp cho tiện ích quyền truy cập vào API browser.proxy để quản lý chế độ cài đặt proxy của Chrome.
`"tts"`	API browser.tts phát văn bản tổng hợp sang lời nói (TTS).
`"ttsEngine"`	API browser.ttsEngine triển khai một 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 browser.wallpaper để thay đổi hình nền ChromeOS.

Hãy 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 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.
  browser.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:

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 một nhóm quyền cụ thể hay không, hãy sử dụng permission.contains():

browser.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 dùng nữa. Sau khi một quyền bị xoá, việc gọi permissions.request() thường sẽ thêm lại quyền đó mà không nhắc người dùng.

browser.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ủ lưu trữ, 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 liên kết với Kịch bản 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()

Chrome 133 trở lên browser.* kể từ Chrome 148 MV3 trở lên

browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

Thêm yêu cầu cấp quyền 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ủ lưu trữ trong yêu cầu. Yêu cầu sẽ được đặt lại khi điều hướng khác nguồn gốc. Khi được chấp nhận, quyền này sẽ cấp quyền truy cập liên tục vào nguồn gốc hàng đầu của trang web

Thông số

request

đối tượng
- documentId
  
  chuỗi không bắt buộc
  
  Mã nhận dạng của một tài liệu có thể hiển thị các yêu cầu truy cập vào 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 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 có thể hiển thị yêu cầu cấp quyền 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 của máy chủ lưu trữ sẽ chỉ xuất hiện trên những URL khớp với mẫu này.
- tabId
  
  number không bắt buộc
  
  Mã của thẻ có thể hiển thị yêu cầu truy cập vào máy chủ lưu trữ. Nếu được cung cấp, yêu cầu sẽ xuất hiện trên thẻ được chỉ định và bị xoá khi thẻ chuyển đến một nguồn gốc mới. Khi bạn thêm một yêu cầu mới, yêu cầu đó 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.

Giá trị trả về

Promise<void>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

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

Thông số

quyền

Quyền truy cập

Giá trị trả về

Promise<boolean>

Chrome 96 trở lên browser.* kể từ Chrome 148

getAll()

browser.permissions.getAll(): Promise<Permissions>

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

Giá trị trả về

Promise<Permissions>

Chrome 96 trở lên browser.* kể từ Chrome 148

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

Xoá quyền truy cập vào các quyền đã chỉ định. Nếu có bất kỳ vấn đề nào khi xoá quyền, lời hứa sẽ bị từ chối.

Thông số

quyền

Quyền truy cập

Giá trị trả về

Promise<boolean>

Chrome 96 trở lên browser.* kể từ Chrome 148

removeHostAccessRequest()

Chrome 133 trở lên browser.* kể từ Chrome 148 MV3 trở lên

browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

Xoá yêu cầu cấp quyền truy cập của máy chủ lưu trữ (nếu có).

Thông 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 cấp 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 mà yêu cầu truy cập của máy chủ lưu trữ sẽ bị xoá. Nếu được cung cấp, giá trị 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 vào máy chủ lưu trữ hiện có.
- tabId
  
  number không bắt buộc
  
  Mã nhận dạng của thẻ nơi yêu cầu quyền truy cập của máy chủ lưu trữ sẽ bị xoá. Bạn phải chỉ định thuộc tính này hoặc documentId.

Giá trị trả về

Promise<void>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

Yêu cầu quyền truy cập vào các quyền được 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 gốc sẽ bị bỏ qua. Bạn có thể yêu cầu một số quyền không bắt buộc đối với nguồn gố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ó bất kỳ vấn đề nào khi yêu cầu quyền, thì lời hứa sẽ bị từ chối.

Thông số

quyền

Quyền truy cập

Giá trị trả về

Promise<boolean>

Chrome 96 trở lên browser.* kể từ Chrome 148

Sự kiện

onAdded

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

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

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(permissions: Permissions) => void
```
- quyền
  
  Quyền truy cập

onRemoved

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

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

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(permissions: Permissions) => void
```
- quyền
  
  Quyền truy cập

browser.permissions Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mô tả

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

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

Bước 1: Quyết định quyền nào là bắt buộc và quyền nào là không 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

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

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

Bước 5: Xoá quyền

Loại

Permissions

Thuộc tính

Phương thức

addHostAccessRequest()

Thông số

Giá trị trả về

contains()

Thông số

Giá trị trả về

getAll()

Giá trị trả về

remove()

Thông số

Giá trị trả về

removeHostAccessRequest()

Thông số

Giá trị trả về

request()

Thông số

Giá trị trả về

Sự kiện

onAdded

Thông số

onRemoved

Thông số

browser.permissions