chrome.action

Nội dung mô tả

Phạm vi cung cấp

Tệp kê khai

Để sử dụng API chrome.action, hãy chỉ định "manifest_version" của 3 và đưa khoá "action" vào tệp kê khai.

{
  "name": "Action Extension",
  ...
  "action": {
    "default_icon": {              // optional
      "16": "images/icon16.png",   // optional
      "24": "images/icon24.png",   // optional
      "32": "images/icon32.png"    // optional
    },
    "default_title": "Click Me",   // optional, shown in tooltip
    "default_popup": "popup.html"  // optional
  },
  ...
}

Khoá "action" (cùng với các khoá con) là không bắt buộc. Khi không được đưa vào, tiện ích của bạn vẫn được hiển thị trong thanh công cụ để cung cấp quyền truy cập vào trình đơn của tiện ích. Vì lý do này, bạn nên sử dụng ít nhất các khoá "action" và "default_icon".

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

Các thành phần của giao diện người dùng

Biểu tượng

Biểu tượng này là hình ảnh chính trên thanh công cụ cho tiện ích của bạn và được đặt bằng khoá "default_icon" trong khoá "action" của tệp kê khai. Biểu tượng phải có 16 pixel độc lập với thiết bị (DIP) rộng và cao.

Khoá "default_icon" là từ điển về kích thước cho đường dẫn hình ảnh. Chrome dùng các biểu tượng này để chọn tỷ lệ hình ảnh sẽ sử dụng. Nếu không tìm thấy kết quả trùng khớp hoàn toàn, Chrome sẽ chọn hình ảnh có sẵn gần nhất và điều chỉnh tỷ lệ cho vừa với hình ảnh. Điều này có thể ảnh hưởng đến chất lượng hình ảnh.

Vì các thiết bị có hệ số tỷ lệ ít phổ biến hơn như 1,5x hoặc 1,2x ngày càng trở nên phổ biến, do đó bạn nên cung cấp nhiều kích thước cho biểu tượng. Điều này cũng đảm bảo tiện ích của bạn có khả năng chống lại các thay đổi có thể xảy ra về kích thước hiển thị biểu tượng trong tương lai. Tuy nhiên, nếu chỉ cung cấp một kích thước duy nhất, thì bạn cũng có thể đặt khoá "default_icon" thành một chuỗi có đường dẫn đến một biểu tượng duy nhất thay vì từ điển.

Bạn cũng có thể gọi action.setIcon() để đặt biểu tượng của tiện ích theo phương thức lập trình bằng cách chỉ định một đường dẫn hình ảnh khác hoặc cung cấp biểu tượng được tạo tự động bằng phần tử canvas HTML, hoặc nếu bạn đặt từ trình chạy dịch vụ tiện ích, thì API canvas ngoài màn hình.

const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00';  // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

Đối với các tiện ích đóng gói (được cài đặt từ tệp .crx), hình ảnh có thể ở hầu hết các định dạng mà công cụ hiển thị Blink có thể hiển thị, bao gồm PNG, JPEG, BMP, ICO và các định dạng khác. SVG không được hỗ trợ. Tiện ích đã giải nén phải sử dụng hình ảnh PNG.

Chú thích (tiêu đề)

Chú thích hoặc tiêu đề sẽ xuất hiện khi người dùng giữ con trỏ chuột trên biểu tượng của tiện ích trên thanh công cụ. Nhãn này cũng có trong văn bản có thể tiếp cận được trình đọc màn hình đọc khi nút này được lấy tiêu điểm.

Chú thích mặc định được đặt bằng trường "default_title" của khoá "action" trong manifest.json. Bạn cũng có thể thiết lập chế độ này theo phương thức lập trình bằng cách gọi action.setTitle().

Huy hiệu

Thao tác có thể tuỳ ý hiển thị một "huy hiệu" – một phần văn bản nằm trên biểu tượng. Điều này cho phép bạn cập nhật thao tác để hiển thị một lượng nhỏ thông tin về trạng thái của tiện ích, chẳng hạn như bộ đếm. Huy hiệu có một thành phần văn bản và một màu nền. Vì không gian bị giới hạn, văn bản huy hiệu chỉ nên sử dụng tối đa 4 ký tự.

Để tạo huy hiệu, hãy đặt huy hiệu theo phương thức lập trình bằng cách gọi action.setBadgeBackgroundColor() và action.setBadgeText(). Không có chế độ cài đặt huy hiệu mặc định trong tệp kê khai. Giá trị màu huy hiệu có thể là một mảng gồm bốn số nguyên từ 0 đến 255 tạo nên màu RGBA của huy hiệu hoặc một chuỗi có giá trị màu CSS.

chrome.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

Cửa sổ bật lên

Một cửa sổ bật lên của một thao tác sẽ hiển thị khi người dùng nhấp vào nút hành động của tiện ích trên thanh công cụ. Cửa sổ bật lên có thể chứa bất kỳ nội dung HTML nào bạn thích và sẽ được tự động định kích thước cho vừa với nội dung. Kích thước của cửa sổ bật lên phải nằm trong khoảng từ 25x25 đến 800x600 pixel.

Ban đầu, cửa sổ bật lên được thuộc tính "default_popup" thiết lập trong khoá "action" của tệp manifest.json. Nếu có, thuộc tính này phải trỏ đến một đường dẫn tương đối trong thư mục tiện ích. Bạn cũng có thể cập nhật phương thức này một cách linh động để trỏ đến một đường dẫn tương đối khác bằng phương thức action.setPopup().

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

Trạng thái trên mỗi thẻ

Các thao tác với tiện ích có thể có trạng thái khác nhau cho mỗi thẻ. Để đặt giá trị cho một thẻ riêng lẻ, hãy sử dụng thuộc tính tabId trong các phương thức cài đặt của API action. Ví dụ: để đặt văn bản huy hiệu cho một thẻ cụ thể, hãy làm như sau:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

chrome.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

Nếu thuộc tính tabId không được dùng nữa, thì chế độ cài đặt này sẽ được coi là một chế độ cài đặt chung. Chế độ cài đặt dành riêng cho thẻ được ưu tiên hơn so với chế độ cài đặt chung.

Trạng thái bật

Theo mặc định, các thao tác trên thanh công cụ được bật (có thể nhấp) trên mọi thẻ. Bạn có thể kiểm soát việc này bằng cách sử dụng phương thức action.enable() và action.disable(). Điều này chỉ ảnh hưởng đến việc cửa sổ bật lên (nếu có) hoặc sự kiện action.onClicked có được gửi đến tiện ích của bạn hay không; chứ không ảnh hưởng đến sự hiện diện của thao tác đó trong thanh công cụ.

Ví dụ

Các ví dụ sau đây cho thấy một số cách phổ biến mà các hành động được sử dụng trong tiện ích. Để dùng thử API này, hãy cài đặt ví dụ về Action API trong kho lưu trữ chrome-extension-samples.

Hiện cửa sổ bật lên

Thông thường, một tiện ích sẽ hiển thị cửa sổ bật lên khi người dùng nhấp vào thao tác của tiện ích. Để triển khai việc này trong tiện ích của riêng bạn, hãy khai báo cửa sổ bật lên trong manifest.json và chỉ định nội dung mà Chrome sẽ hiển thị trong cửa sổ bật lên.

// manifest.json
{
  "name": "Action popup demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to view a popup",
    "default_popup": "popup.html"
  }
}

<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    html {
      min-height: 5em;
      min-width: 10em;
      background: salmon;
    }
  </style>
</head>
<body>
  <p>Hello, world!</p>
</body>
</html>

Chèn tập lệnh nội dung khi nhấp chuột

Một mẫu hình phổ biến cho các tiện ích là hiện tính năng chính của tiện ích bằng thao tác của tiện ích. Ví dụ sau minh hoạ cho mẫu này. Khi người dùng nhấp vào thao tác đó, tiện ích sẽ chèn một tập lệnh nội dung vào trang hiện tại. Sau đó, tập lệnh nội dung sẽ hiển thị cảnh báo để xác minh rằng mọi thứ hoạt động như mong đợi.

// manifest.json
{
  "name": "Action script injection demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to show an alert"
  },
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  }
}

// background.js
chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});

// content.js
alert('Hello, world!');

Mô phỏng các hành động bằng declarativeContent

Ví dụ này cho thấy cách logic nền của tiện ích có thể (a) vô hiệu hoá một thao tác theo mặc định và (b) sử dụng declarativeContent để cho phép thao tác đó trên các trang web cụ thể.

// service-worker.js

// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  chrome.action.disable();

  // Clear all rules to ensure only our expected rules are set
  chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new chrome.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new chrome.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    chrome.declarativeContent.onPageChanged.addRules(rules);
  });
});

chrome.action.disable(
  tabId?: number,
  callback?: function,
)

chrome.action.enable(
  tabId?: number,
  callback?: function,
)

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
)

chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

chrome.action.getUserSettings(
  callback?: function,
)

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

chrome.action.setIcon(
  details: object,
  callback?: function,
)

chrome.action.setPopup(
  details: object,
  callback?: function,
)

chrome.action.setTitle(
  details: object,
  callback?: function,
)

chrome.action.onClicked.addListener(
  callback: function,
)