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

Mô tả

Sử dụng API chrome.runtime để truy xuất trình chạy dịch vụ, trả về thông tin chi tiết về tệp kê khai, đồng thời lắng nghe và phản hồi các sự kiện trong vòng đời của tiện ích. Bạn cũng có thể sử dụng API này để chuyển đổi đường dẫn tương đối của URL thành URL đủ điều kiện.

Hầu hết các thành phần của API này đều không yêu cầu bất kỳ quyền nào. Bạn cần có quyền này cho connectNative(), sendNativeMessage() và onNativeConnect.

Ví dụ sau đây cho biết cách khai báo quyền "nativeMessaging" trong tệp kê khai:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

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

Runtime API cung cấp các phương thức hỗ trợ một số lĩnh vực mà các tiện ích của bạn có thể sử dụng:

Truyền thông báo: Tiện ích của bạn có thể giao tiếp với các bối cảnh khác nhau trong tiện ích của bạn và cả với các tiện ích khác bằng cách sử dụng các phương thức và sự kiện sau: connect(), onConnect, onConnectExternal, sendMessage(), onMessage và onMessageExternal. Ngoài ra, tiện ích của bạn có thể truyền thông báo đến các ứng dụng gốc trên thiết bị của người dùng bằng cách sử dụng connectNative() và sendNativeMessage().

Truy cập vào siêu dữ liệu của tiện ích và nền tảng: Các phương thức này cho phép bạn truy xuất một số phần siêu dữ liệu cụ thể về tiện ích và nền tảng. Các phương thức trong danh mục này bao gồm getManifest() và getPlatformInfo().
Quản lý vòng đời và các lựa chọn của tiện ích: Các thuộc tính này cho phép bạn thực hiện một số thao tác meta trên tiện ích và hiển thị trang tuỳ chọn. Các phương thức và sự kiện trong danh mục này bao gồm onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() và setUninstallURL().
Tiện ích trợ lý: Các phương thức này cung cấp tiện ích như chuyển đổi các biểu thị tài nguyên nội bộ sang định dạng bên ngoài. Các phương thức trong danh mục này bao gồm getURL().
Tiện ích ở chế độ Kiosk: Các phương thức này chỉ có trên ChromeOS và chủ yếu dùng để hỗ trợ việc triển khai chế độ kiosk. Các phương thức trong danh mục này bao gồm restart() và restartAfterDelay()`.

Hành vi của tiện ích đã giải nén

Khi một tiện ích đã giải nén được tải lại, thao tác này được coi là một bản cập nhật. Điều này có nghĩa là sự kiện browser.runtime.onInstalled sẽ kích hoạt với lý do "update". Điều này bao gồm cả trường hợp tiện ích được tải lại bằng browser.runtime.reload().

Trường hợp sử dụng

Thêm hình ảnh vào trang web

Để truy cập vào một tài sản được lưu trữ trên một miền khác, trang web phải chỉ định URL đầy đủ của tài nguyên (ví dụ: <img src="https://example.com/logo.png">). Điều này cũng đúng khi bạn muốn thêm một tài sản tiện ích vào trang web. Hai điểm khác biệt là tài sản của tiện ích phải được hiển thị dưới dạng tài nguyên có thể truy cập trên web và thông thường, tập lệnh nội dung chịu trách nhiệm chèn tài sản của tiện ích.

Trong ví dụ này, tiện ích sẽ thêm logo.png vào trang mà content script đang được chèn vào bằng cách sử dụng runtime.getURL() để tạo một URL đủ điều kiện. Nhưng trước tiên, tài sản phải được khai báo là một tài nguyên có thể truy cập trên web trong tệp kê khai.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = browser.runtime.getURL('logo.png');
  document.body.append(img);
}

Gửi dữ liệu từ một tập lệnh nội dung đến trình chạy dịch vụ

Thông thường, tập lệnh nội dung của tiện ích cần dữ liệu do một phần khác của tiện ích quản lý, chẳng hạn như trình chạy dịch vụ. Tương tự như hai cửa sổ trình duyệt được mở cho cùng một trang web, hai ngữ cảnh này không thể truy cập trực tiếp vào các giá trị của nhau. Thay vào đó, tiện ích có thể sử dụng truyền thông điệp để phối hợp trên các bối cảnh khác nhau này.

Trong ví dụ này, tập lệnh nội dung cần một số dữ liệu từ trình chạy dịch vụ của tiện ích để khởi động giao diện người dùng. Để lấy dữ liệu này, nó sẽ truyền thông báo get-user-data do nhà phát triển xác định đến trình chạy dịch vụ và phản hồi bằng một bản sao thông tin của người dùng.

content.js:

// 1. Send a message to the service worker requesting the user's data
browser.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

Thu thập ý kiến phản hồi về việc gỡ cài đặt

Nhiều tiện ích sử dụng các cuộc khảo sát sau khi gỡ cài đặt để tìm hiểu cách tiện ích có thể phục vụ người dùng tốt hơn và cải thiện khả năng giữ chân. Ví dụ sau đây cho thấy cách thêm chức năng này.

background.js:

browser.runtime.onInstalled.addListener(details => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    browser.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

Ví dụ

Hãy xem Manifest V3 – Bản minh hoạ Tài nguyên có thể truy cập trên web để biết thêm ví dụ về Runtime API.

Loại

ContextFilter

Chrome 114 trở lên

Một bộ lọc để so khớp với một số bối cảnh tiện ích nhất định. Các bối cảnh trùng khớp phải khớp với tất cả bộ lọc được chỉ định; mọi bộ lọc không được chỉ định sẽ khớp với tất cả bối cảnh có sẵn. Do đó, bộ lọc `{}` sẽ khớp với tất cả các ngữ cảnh có sẵn.

Thuộc tính

contextIds

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

ContextType[] không bắt buộc
documentIds

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

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

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

number[] không bắt buộc
ẩn danh

boolean không bắt buộc
tabIds

number[] không bắt buộc
windowIds

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

ContextType

Chrome 114 trở lên

Enum

"TAB"
Chỉ định loại bối cảnh là thẻ

"POPUP"
Chỉ định loại ngữ cảnh là cửa sổ bật lên của tiện ích

"BACKGROUND"
Chỉ định loại bối cảnh là một trình chạy dịch vụ.

"OFFSCREEN_DOCUMENT"
Chỉ định loại bối cảnh là tài liệu hiển thị bên ngoài màn hình.

"SIDE_PANEL"
Chỉ định loại bối cảnh là bảng điều khiển bên.

"DEVELOPER_TOOLS"
Chỉ định loại bối cảnh là công cụ cho nhà phát triển.

ExtensionContext

Chrome 114 trở lên

Một bối cảnh lưu trữ nội dung của tiện ích.

Thuộc tính

contextId

chuỗi

Giá trị nhận dạng duy nhất cho bối cảnh này
contextType

ContextType

Loại bối cảnh mà thông tin này tương ứng.
documentId

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

Một UUID cho tài liệu được liên kết với bối cảnh này hoặc không xác định nếu bối cảnh này không được lưu trữ trong tài liệu.
documentOrigin

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

Nguồn gốc của tài liệu được liên kết với ngữ cảnh này hoặc không xác định nếu ngữ cảnh không được lưu trữ trong tài liệu.
documentUrl

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

URL của tài liệu được liên kết với ngữ cảnh này hoặc không xác định nếu ngữ cảnh không được lưu trữ trong tài liệu.
frameId

số

Mã nhận dạng của khung cho ngữ cảnh này hoặc -1 nếu ngữ cảnh này không được lưu trữ trong khung.
ẩn danh

boolean

Liệu bối cảnh có được liên kết với một hồ sơ ẩn danh hay không.
tabId

số

Mã nhận dạng của thẻ cho ngữ cảnh này hoặc -1 nếu ngữ cảnh này không được lưu trữ trong thẻ.
windowId

số

Mã nhận dạng của cửa sổ cho ngữ cảnh này hoặc -1 nếu ngữ cảnh này không được lưu trữ trong một cửa sổ.

MessageSender

Một đối tượng chứa thông tin về ngữ cảnh tập lệnh đã gửi một thông báo hoặc yêu cầu.

Thuộc tính

documentId

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

Chrome 106 trở lên

UUID của tài liệu đã mở kết nối.
documentLifecycle

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

Chrome 106 trở lên

Vòng đời của tài liệu đã mở kết nối tại thời điểm cổng được tạo. Xin lưu ý rằng trạng thái vòng đời của tài liệu có thể đã thay đổi kể từ khi bạn tạo cổng.
frameId

number không bắt buộc

Khung đã mở kết nối. 0 cho khung cấp cao nhất, số dương cho khung con. Tham số này sẽ chỉ được đặt khi bạn đặt tab.
id

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

Mã nhận dạng của tiện ích đã mở kết nối (nếu có).
nativeApplication

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

Chrome 74 trở lên

Tên của ứng dụng gốc đã mở kết nối (nếu có).
nguồn gốc

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

Chrome 80 trở lên

Nguồn gốc của trang hoặc khung đã mở kết nối. Giá trị này có thể khác với thuộc tính url (ví dụ: about:blank) hoặc có thể là giá trị mờ (ví dụ: iframe được cách ly). Điều này hữu ích khi xác định xem nguồn có đáng tin cậy hay không nếu chúng ta không thể xác định ngay từ URL.
thẻ

Thẻ không bắt buộc

tabs.Tab đã mở kết nối, nếu có. Thuộc tính này chỉ xuất hiện khi kết nối được mở từ một thẻ (bao gồm cả tập lệnh nội dung) và chỉ khi receiver là một tiện ích chứ không phải ứng dụng.
tlsChannelId

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

Mã nhận dạng kênh TLS của trang hoặc khung đã mở kết nối, nếu tiện ích yêu cầu và nếu có.
url

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

URL của trang hoặc khung đã mở kết nối. Nếu người gửi nằm trong một iframe, thì đó sẽ là URL của iframe chứ không phải URL của trang lưu trữ iframe đó.

OnInstalledReason

Chrome 44 trở lên

Lý do sự kiện này được gửi đi.

Enum

"install"
Chỉ định lý do của sự kiện là cài đặt.

"update"
Chỉ định lý do của sự kiện là nội dung cập nhật tiện ích.

"chrome_update"
Chỉ định lý do của sự kiện là bản cập nhật Chrome.

"shared_module_update"
Chỉ định lý do của sự kiện là nội dung cập nhật cho một mô-đun dùng chung.

OnRestartRequiredReason

Chrome 44 trở lên

Lý do sự kiện được gửi đi. "app_update" được dùng khi cần khởi động lại vì ứng dụng được cập nhật lên phiên bản mới hơn. "os_update" được dùng khi cần khởi động lại vì trình duyệt/hệ điều hành được cập nhật lên phiên bản mới hơn. "periodic" được dùng khi hệ thống chạy lâu hơn thời gian hoạt động được phép mà bạn đặt trong chính sách doanh nghiệp.

Enum

"app_update"
Chỉ định lý do của sự kiện là bản cập nhật cho ứng dụng.

"os_update"
Chỉ định lý do của sự kiện là bản cập nhật cho hệ điều hành.

"periodic"
Chỉ định lý do xảy ra sự kiện là ứng dụng khởi động lại định kỳ.

PlatformArch

Chrome 44 trở lên

Cấu trúc bộ xử lý của máy.

Enum

"arm"
Chỉ định cấu trúc bộ xử lý là arm.

"arm64"
Chỉ định kiến trúc bộ xử lý là arm64.

"x86-32"
Chỉ định cấu trúc bộ xử lý là x86-32.

"x86-64"

browser.runtime 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

Hành vi của tiện ích đã giải nén

Trường hợp sử dụng

Thêm hình ảnh vào trang web

Gửi dữ liệu từ một tập lệnh nội dung đến trình chạy dịch vụ

Thu thập ý kiến phản hồi về việc gỡ cài đặt

Ví dụ

Loại

ContextFilter

Thuộc tính

ContextType

Enum

ExtensionContext

Thuộc tính

MessageSender

Thuộc tính

OnInstalledReason

Enum

OnRestartRequiredReason

Enum

PlatformArch

Enum

browser.runtime