chrome.action

Mô tả

Phạm vi cung cấp

Tệp kê khai

Để sử dụng API chrome.action, hãy chỉ định một "manifest_version" là 3 và thêm 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ó biểu tượng, tiện ích của bạn vẫn xuất hiện trên 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 luôn thêm ít nhất các khoá "action" và "default_icon".

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

Các 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ụ của tiện ích và được đặt bằng khoá "default_icon" trong khoá "action" của tệp kê khai. Biểu tượng phải có chiều rộng và chiều cao là 16 pixel độc lập với thiết bị (DIP).

Khoá "default_icon" là một từ điển về kích thước cho các đường dẫn đến hình ảnh. Chrome sử dụng các biểu tượng này để chọn tỷ lệ hình ảnh cần 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 kết quả gần nhất có sẵn 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 như 1,5x hoặc 1,2x đang trở nên phổ biến hơn, nên bạn nên cung cấp nhiều kích thước cho biểu tượng của mình. Điều này cũng giúp tiện ích của bạn không bị ảnh hưởng khi kích thước hiển thị biểu tượng có thể thay đổi trong tương lai. Tuy nhiên, nếu chỉ cung cấp một kích thước, 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ì một từ điển.

Bạn cũng có thể gọi action.setIcon() để đặt biểu tượng của tiện ích theo cách 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 động bằng phần tử canvas HTML hoặc nếu đặt từ một worker 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 được đó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ụ kết xuất Blink có thể hiển thị, bao gồm PNG, JPEG, BMP, ICO và các định dạng khác. Không hỗ trợ SVG. Phần mở rộng chưa đóng gói phải sử dụng hình ảnh PNG.

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

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

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

Huy hiệu

Các thao tác có thể tuỳ ý hiển thị một "huy hiệu" – một đoạn văn bản được xếp lớp lên biểu tượng. Thao tác 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ư một 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 có hạn, nên bạn nên sử dụng văn bản huy hiệu có tối đa 4 ký tự.

Để tạo một huy hiệu, hãy đặt huy hiệu đó theo cách 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 của huy hiệu có thể là một mảng gồm 4 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

Cửa sổ bật lên của một thao tác sẽ xuất hiện khi người dùng nhấp vào nút thao tác của tiện ích trên thanh công cụ. Cửa sổ bật lên có thể chứa mọi nội dung HTML mà bạn muốn và sẽ tự động điều chỉnh kích thước cho phù hợp với nội dung của nó. 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 đặt theo thuộc tính "default_popup" trong khoá "action" trong 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 độ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 theo thẻ

Hành động trên tiện ích có thể có nhiều trạng thái cho từng thẻ. Để đặt giá trị cho từng thẻ, hãy 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 bạn bỏ qua thuộc tính tabId, thì chế độ cài đặt này sẽ được coi là chế độ cài đặt chung. Chế độ cài đặt dành riêng cho thẻ sẽ được ưu tiên hơn 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ụ sẽ được bật (có thể nhấp vào) trên mọi thẻ. Bạn có thể thay đổi giá trị mặc định này bằng cách đặt thuộc tính default_state trong khoá action của tệp kê khai. Nếu default_state được đặt thành "disabled", thì thao tác này sẽ bị vô hiệu hoá theo mặc định và phải được bật theo phương thức lập trình để có thể nhấp vào. Nếu default_state được đặt thành "enabled" (mặc định), thì thao tác này sẽ được bật và có thể nhấp vào theo mặc định.

Bạn có thể kiểm soát trạng thái theo phương thức lập trình bằng cách sử dụng các 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; điều này 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 thao tác được 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, tiện ích sẽ hiển thị một cửa sổ bật lên khi người dùng nhấp vào hành động 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

Một mẫu hình phổ biến cho các tiện ích là hiển thị tính năng chính của chúng bằng cách sử dụng thao tác của tiện ích. Ví dụ sau đây minh hoạ mẫu này. Khi người dùng nhấp vào thao tác này, 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ị một cảnh báo để xác minh rằng mọi thứ đều 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 thao tác bằng declarativeContent

Ví dụ này cho thấy cách logic nền của một tiện ích có thể (a) tắt một thao tác theo mặc định và (b) sử dụng declarativeContent để bật 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,
): Promise<void>

chrome.action.enable(
  tabId?: number,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

chrome.action.setPopup(
  details: object,
): Promise<void>

chrome.action.setTitle(
  details: object,
): Promise<void>

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

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