chrome.action

Mô tả

Sử dụng API chrome.action để kiểm soát biểu tượng của tiện ích trong thanh công cụ Google Chrome.

Các biểu tượng thao tác sẽ xuất hiện trong thanh công cụ của trình duyệt bên cạnh omnibox. Sau khi cài đặt, các tiện ích này sẽ xuất hiện trong trình đơn tiện ích (biểu tượng mảnh ghép). Người dùng có thể ghim biểu tượng tiện ích của bạn vào thanh công cụ.

Phạm vi cung cấp

Chrome 88 trở lên MV3 trở lên

Tệp kê khai

Bạn phải khai báo các khoá sau trong tệp kê khai để sử dụng API này.

"action"

Để 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ó phần này, tiện ích của bạn vẫn xuất hiện 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 luôn đưa vào í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 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ó 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 đến đường dẫ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 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 kết quả gần nhất có sẵn và điều chỉnh theo 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 phổ biến, nên bạn nên cung cấp nhiều kích thước cho biểu tượng. Điều này cũng giúp phần mở rộng của bạn an toàn trước những thay đổi tiềm ẩn về kích thước hiển thị biểu tượng. 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 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 động bằng phần tử canvas HTML hoặc API canvas ngoài màn hình (nếu đặt từ một worker dịch vụ tiện ích).

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ụ 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. Các phần mở rộng chưa giải nén phải sử dụng hình ảnh PNG.

Chú giải công cụ (tiêu đề)

Chú giải công cụ 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 trong thanh công cụ. Thông tin này cũng được đưa vào 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 tâm đ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 hành động có thể tuỳ ý hiển thị "huy hiệu" — một đoạn văn bản được xếp chồng lê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 có hạn, bạn nên sử dụng tối đa 4 ký tự cho văn bản trên huy hiệu.

Để tạo 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 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
  () => { /* ... */ },
);

Một cửa sổ bật lên của thao tác sẽ xuất hiện khi người dùng nhấp vào nút hành động của tiện ích trong 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 muốn và sẽ tự động được định cỡ cho phù hợp với nội dung của cửa sổ. 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 bằng 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 mở rộng. 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ẻ

Các thao tác của tiện ích có thể có trạng thái khác nhau cho từng 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 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ẻ đượ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ụ được bật (có thể nhấp) 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 bạn đặt default_state thành "disabled", thao tác này sẽ bị tắt 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 bạn đặt default_state thành "enabled" (mặc định), thì thao tác này sẽ được bật và có thể nhấp 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 liệu 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; nó 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 để sử dụng thao tác trong tiện ích. Để dùng thử API này, hãy cài đặt ví dụ về API Hành động từ kho lưu trữ chrome-extension-samples.

Hiển thị cửa sổ bật lên

Thông thường, một 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 tính năng 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 phổ biến cho các tiện ích là hiển thị tính năng chính 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 hành động, 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 hành động bằng declarativeContent

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

Loại

OpenPopupOptions

Chrome 99 trở lên

Thuộc tính

  • windowId

    số không bắt buộc

    Mã nhận dạng của cửa sổ để mở cửa sổ bật lên cho thao tác. Mặc định là cửa sổ đang hoạt động nếu bạn không chỉ định.

TabDetails

Thuộc tính

  • tabId

    số không bắt buộc

    Mã của thẻ để truy vấn trạng thái. Nếu không chỉ định thẻ nào, thì trạng thái không dành riêng cho thẻ sẽ được trả về.

UserSettings

Chrome 91 trở lên

Tập hợp các chế độ cài đặt do người dùng chỉ định liên quan đến hành động của một tiện ích.

Thuộc tính

  • isOnToolbar

    boolean

    Liệu biểu tượng thao tác của tiện ích có hiển thị trên thanh công cụ cấp cao nhất của cửa sổ trình duyệt hay không (tức là liệu người dùng có "ghim" tiện ích đó hay không).

UserSettingsChange

Chrome 130 trở lên

Thuộc tính

  • isOnToolbar

    boolean không bắt buộc

    Liệu biểu tượng thao tác của tiện ích có hiển thị trên thanh công cụ cấp cao nhất của cửa sổ trình duyệt hay không (tức là liệu người dùng đã "ghim" tiện ích đó hay chưa).

Phương thức

disable()

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

Tắt thao tác cho một thẻ.

Tham số

  • tabId

    số không bắt buộc

    Mã của thẻ mà bạn muốn sửa đổi hành động.

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

enable()

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

Bật thao tác cho một thẻ. Theo mặc định, các thao tác sẽ được bật.

Tham số

  • tabId

    số không bắt buộc

    Mã của thẻ mà bạn muốn sửa đổi hành động.

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

getBadgeBackgroundColor()

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

Lấy màu nền của thao tác.

Tham số

  • chi tiết

    TabDetails

  • lệnh gọi lại

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

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

    (result: ColorArray) => void

Giá trị trả về

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

getBadgeText()

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

Lấy văn bản huy hiệu của hành động. Nếu không chỉ định thẻ nào, thì văn bản huy hiệu không dành riêng cho thẻ sẽ được trả về. Nếu bạn bật displayActionCountAsBadgeText, hệ thống sẽ trả về văn bản phần giữ chỗ trừ phi bạn có quyền declarativeNetRequestFeedback hoặc đã cung cấp văn bản huy hiệu dành riêng cho thẻ.

Tham số

  • chi tiết

    TabDetails

  • lệnh gọi lại

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

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

    (result: string) => void

    • kết quả

      chuỗi

Giá trị trả về

  • Promise<string>

    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.

getBadgeTextColor()

Lời hứa Chrome 110 trở lên 
chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

Lấy màu văn bản của thao tác.

Tham số

  • chi tiết

    TabDetails

  • lệnh gọi lại

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

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

    (result: ColorArray) => void

Giá trị trả về

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

getPopup()

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

Đặt tài liệu html làm cửa sổ bật lên cho hành động này.

Tham số

  • chi tiết

    TabDetails

  • lệnh gọi lại

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

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

    (result: string) => void

    • kết quả

      chuỗi

Giá trị trả về

  • Promise<string>

    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.

getTitle()

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

Lấy tiêu đề của thao tác.

Tham số

  • chi tiết

    TabDetails

  • lệnh gọi lại

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

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

    (result: string) => void

    • kết quả

      chuỗi

Giá trị trả về

  • Promise<string>

    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.

getUserSettings()

Lời hứa Chrome 91 trở lên 
chrome.action.getUserSettings(
  callback?: function,
)

Trả về các chế độ cài đặt do người dùng chỉ định liên quan đến hành động của một 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: 

    (userSettings: UserSettings) => void

Giá trị trả về

  • Promise<UserSettings>

    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.

isEnabled()

Lời hứa Chrome 110 trở lên 
chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

Cho biết liệu thao tác mở rộng có được bật cho một thẻ hay không (hoặc trên toàn cục nếu không có tabId nào được cung cấp). Các hành động được bật chỉ bằng declarativeContent luôn trả về giá trị false.

Tham số

  • tabId

    số không bắt buộc

    Mã của thẻ mà bạn muốn kiểm tra trạng thái đã bật.

  • lệnh gọi lại

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

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

    (isEnabled: boolean) => void

    • isEnabled

      boolean

      Đúng nếu hành động tiện ích được bật.

Giá trị trả về

  • Promise<boolean>

    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.

openPopup()

Promise Chrome 127 trở lên 
chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

Mở cửa sổ bật lên của tiện ích. Từ Chrome 118 đến Chrome 126, tính năng này chỉ dành cho các tiện ích được cài đặt theo chính sách.

Tham số

  • tùy chọn

    OpenPopupOptions không bắt buộc

    Chỉ định các tuỳ chọn để mở cửa sổ bật lên.

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

setBadgeBackgroundColor()

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

Đặt màu nền cho huy hiệu.

Tham số

  • chi tiết

    đối tượng

    • màu

      string | ColorArray

      Một mảng gồm 4 số nguyên trong khoảng [0,255] tạo nên màu RGBA của huy hiệu. Ví dụ: màu đỏ mờ là [255, 0, 0, 255]. Cũng có thể là một chuỗi có giá trị CSS, với màu đỏ mờ là #FF0000 hoặc #F00.

    • tabId

      số không bắt buộc

      Giới hạn thay đổi ở thời điểm bạn chọn một thẻ cụ thể. Tự động đặt lại khi thẻ bị đóng.

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

setBadgeText()

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

Đặt văn bản huy hiệu cho hành động. Huy hiệu sẽ xuất hiện ở đầu biểu tượng.

Tham số

  • chi tiết

    đối tượng

    • tabId

      số không bắt buộc

      Giới hạn thay đổi ở thời điểm bạn chọn một thẻ cụ thể. Tự động đặt lại khi thẻ bị đóng.

    • văn bản

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

      Bạn có thể truyền số lượng ký tự bất kỳ, nhưng chỉ khoảng 4 ký tự có thể vừa với không gian. Nếu bạn truyền một chuỗi trống (''), văn bản huy hiệu sẽ bị xoá. Nếu bạn chỉ định tabId và text là giá trị rỗng, thì văn bản cho thẻ đã chỉ định sẽ bị xoá và mặc định là văn bản huy hiệu chung.

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

setBadgeTextColor()

Lời hứa Chrome 110 trở lên 
chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

Đặt màu văn bản cho huy hiệu.

Tham số

  • chi tiết

    đối tượng

    • màu

      string | ColorArray

      Một mảng gồm 4 số nguyên trong khoảng [0,255] tạo nên màu RGBA của huy hiệu. Ví dụ: màu đỏ mờ là [255, 0, 0, 255]. Cũng có thể là một chuỗi có giá trị CSS, với màu đỏ mờ là #FF0000 hoặc #F00. Nếu bạn không đặt giá trị này, hệ thống sẽ tự động chọn một màu tương phản với màu nền của huy hiệu để văn bản có thể hiển thị. Màu có giá trị alpha tương đương với 0 sẽ không được đặt và sẽ trả về lỗi.

    • tabId

      số không bắt buộc

      Giới hạn thay đổi ở thời điểm bạn chọn một thẻ cụ thể. Tự động đặt lại khi thẻ bị đóng.

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

setIcon()

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

Đặt biểu tượng cho thao tác. Bạn có thể chỉ định biểu tượng dưới dạng đường dẫn đến tệp hình ảnh hoặc dưới dạng dữ liệu pixel từ phần tử canvas hoặc dưới dạng từ điển của một trong hai loại đó. Bạn phải chỉ định thuộc tính path hoặc imageData.

Tham số

  • chi tiết

    đối tượng

    • imageData

      ImageData | đối tượng không bắt buộc

      Một đối tượng ImageData hoặc một từ điển {size -> ImageData} đại diện cho biểu tượng cần đặt. Nếu biểu tượng được chỉ định là từ điển, thì hình ảnh thực tế sẽ được chọn tuỳ thuộc vào mật độ pixel của màn hình. Nếu số pixel hình ảnh vừa với một đơn vị không gian màn hình bằng scale, thì hình ảnh có kích thước scale * n sẽ được chọn, trong đó n là kích thước của biểu tượng trong giao diện người dùng. Bạn phải chỉ định ít nhất một hình ảnh. Lưu ý rằng "details.imageData = foo" tương đương với "details.imageData = {'16': foo}"

    • đường dẫn

      string | object không bắt buộc

      Đường dẫn hình ảnh tương đối hoặc từ điển {size -> relative image path} trỏ đến biểu tượng cần đặt. Nếu biểu tượng được chỉ định là từ điển, thì hình ảnh thực tế sẽ được chọn tuỳ thuộc vào mật độ pixel của màn hình. Nếu số pixel hình ảnh vừa với một đơn vị không gian màn hình bằng scale, thì hình ảnh có kích thước scale * n sẽ được chọn, trong đó n là kích thước của biểu tượng trong giao diện người dùng. Bạn phải chỉ định ít nhất một hình ảnh. Lưu ý rằng "details.path = foo" tương đương với "details.path = {'16': foo}"

    • tabId

      số không bắt buộc

      Giới hạn thay đổi ở thời điểm bạn chọn một thẻ cụ thể. Tự động đặt lại khi thẻ bị đóng.

  • 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>

    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.

setPopup()

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

Đặt tài liệu HTML để mở dưới dạng cửa sổ bật lên khi người dùng nhấp vào biểu tượng của hành động.

Tham số

  • chi tiết

    đối tượng

    • cửa sổ bật lên

      chuỗi

      Đường dẫn tương đối đến tệp HTML để hiển thị trong cửa sổ bật lên. Nếu bạn đặt thành chuỗi trống (''), thì không có cửa sổ bật lên nào xuất hiện.

    • tabId

      số không bắt buộc

      Giới hạn thay đổi ở thời điểm bạn chọn một thẻ cụ thể. Tự động đặt lại khi thẻ bị đóng.

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

setTitle()

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

Đặt tiêu đề của thao tác. Thông tin này sẽ xuất hiện trong chú giải công cụ.

Tham số

  • chi tiết

    đối tượng

    • tabId

      số không bắt buộc

      Giới hạn thay đổi ở thời điểm bạn chọn một thẻ cụ thể. Tự động đặt lại khi thẻ bị đóng.

    • tiêu đề

      chuỗi

      Chuỗi mà hành động sẽ hiển thị khi di chuột qua.

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

Sự kiện

onClicked

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

Được kích hoạt khi người dùng nhấp vào một biểu tượng hành động. Sự kiện này sẽ không kích hoạt nếu hành động có cửa sổ bật lên.

Tham số

  • lệnh gọi lại

    hàm

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

    (tab: tabs.Tab) => void

onUserSettingsChanged

Chrome 130 trở lên 
chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)

Được kích hoạt khi chế độ cài đặt do người dùng chỉ định liên quan đến hành động của một tiện ích thay đổi.

Tham số