chrome.pageAction

refresh date: 2026-09-25 robots: noindex

Mô tả

Sử dụng API chrome.pageAction để đặt biểu tượng trong thanh công cụ chính của Google Chrome, ở bên phải thanh địa chỉ. Thao tác trên trang thể hiện các thao tác có thể thực hiện trên trang hiện tại, nhưng không áp dụng cho tất cả các trang. Các thao tác trên trang sẽ có màu xám khi không hoạt động.

Phạm vi cung cấp

≤ MV2

Một số ví dụ:

  • Đăng ký nguồn cấp dữ liệu RSS của trang này
  • Tạo bản trình chiếu từ ảnh trên trang này

Biểu tượng RSS trong ảnh chụp màn hình sau đây đại diện cho một thao tác trên trang cho phép bạn đăng ký nguồn cấp dữ liệu RSS cho trang hiện tại.

Các thao tác trên trang bị ẩn sẽ có màu xám. Ví dụ: nguồn cấp dữ liệu RSS bên dưới có màu xám vì bạn không thể đăng ký nguồn cấp dữ liệu cho trang hiện tại:

Vui lòng cân nhắc sử dụng hành động của trình duyệt để người dùng luôn có thể tương tác với tiện ích của bạn.

Tệp kê khai

Đăng ký hành động trên trang trong tệp kê khai tiện ích như sau:

{
  "name": "My extension",
  ...
  "page_action": {
    "default_icon": {                    // optional
      "16": "images/icon16.png",           // optional
      "24": "images/icon24.png",           // optional
      "32": "images/icon32.png"            // optional
    },
    "default_title": "Google Mail",      // optional; shown in tooltip
    "default_popup": "popup.html"        // optional
  },
  ...
}

Vì các thiết bị có hệ số tỷ lệ ít phổ biến hơn như 1,5 lần hoặc 1,2 lần đ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. Chrome sẽ chọn biểu tượng gần nhất và điều chỉnh tỷ lệ để lấp đầy không gian 16 dip. Điều này cũng đảm bảo rằng nếu kích thước hiển thị biểu tượng thay đổi, bạn không cần phải làm gì thêm để cung cấp các biểu tượng khác! Tuy nhiên, nếu sự khác biệt về kích thước quá lớn, thì việc điều chỉnh tỷ lệ này có thể khiến biểu tượng bị mất chi tiết hoặc trông mờ.

Cú pháp cũ để đăng ký biểu tượng mặc định vẫn được hỗ trợ:

{
  "name": "My extension",
  ...
  "page_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

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

Giống như thao tác trên trình duyệt, thao tác trên trang có thể có biểu tượng, chú giải công cụ và cửa sổ bật lên; tuy nhiên, chúng không thể có huy hiệu. Ngoài ra, các thao tác trên trang có thể chuyển sang màu xám. Bạn có thể tìm thông tin về biểu tượng, chú giải công cụ và cửa sổ bật lên bằng cách đọc về giao diện người dùng thao tác trên trình duyệt.

Bạn có thể làm cho một thao tác trên trang xuất hiện và chuyển sang màu xám bằng cách sử dụng các phương thức pageAction.show và pageAction.hide tương ứng. Theo mặc định, một thao tác trên trang sẽ có màu xám. Khi hiển thị biểu tượng, bạn chỉ định thẻ mà biểu tượng sẽ xuất hiện. Biểu tượng này vẫn hiển thị cho đến khi thẻ đóng hoặc bắt đầu hiển thị một URL khác (ví dụ: do người dùng nhấp vào một đường liên kết).

Mẹo

Để có tác động trực quan tốt nhất, hãy làm theo các nguyên tắc sau:

  • Nên sử dụng thao tác trên trang cho những tính năng chỉ phù hợp với một vài trang.
  • Đừng sử dụng thao tác trên trang cho những tính năng phù hợp với hầu hết các trang. Thay vào đó, hãy sử dụng hành động của trình duyệt.
  • Không tạo ảnh động liên tục cho biểu tượng. Thật phiền phức.

Loại

ImageDataType

Dữ liệu pixel cho một hình ảnh. Phải là một đối tượng ImageData (ví dụ: từ phần tử canvas).

Loại

ImageData

TabDetails

Chrome 88 trở lên

Thuộc tính

  • tabId

    number không bắt buộc

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

Phương thức

getPopup()

Promise 
chrome.pageAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

Lấy tài liệu html được đặt làm cửa sổ bật lên cho hành động trên trang này.

Thông số

  • chi tiết

    TabDetails

  • callback

    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ề

  • <string> hứa hẹn

    Chrome 101 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getTitle()

Promise 
chrome.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

Thông số

  • chi tiết

    TabDetails

  • callback

    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ề

  • <string> hứa hẹn

    Chrome 101 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

hide()

Promise 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
): Promise<void>

Ẩn thao tác trên trang. Các thao tác trên trang bị ẩn vẫn xuất hiện trên thanh công cụ của Chrome nhưng có màu xám.

Thông số

  • tabId

    số

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

  • callback

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

    Chrome 67 trở lên

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 101 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

setIcon()

Promise 
chrome.pageAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

Đặt biểu tượng cho hành động trên trang. 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 biểu tượng đó. Bạn phải chỉ định thuộc tính path hoặc imageData.

Thông số

  • chi tiết

    đối tượng

    • iconIndex

      number không bắt buộc

      Không dùng nữa. Đối số này bị bỏ qua.

    • imageData

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

      Đối tượng ImageData hoặc 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 dưới dạng từ điển, thì hình ảnh thực tế được sử dụng sẽ được chọn tuỳ thuộc vào mật độ pixel của màn hình. Nếu số lượng điểm ả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 dưới dạng từ điển, thì hình ảnh thực tế được sử dụng sẽ được chọn tuỳ thuộc vào mật độ pixel của màn hình. Nếu số lượng điểm ả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ố

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

  • callback

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

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 101 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

setPopup()

Promise 
chrome.pageAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

Đặt tài liệu HTML sẽ được 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 trên trang.

Thông 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 chính sách này 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ố

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

  • callback

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

    Chrome 67 trở lên

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 101 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

setTitle()

Promise 
chrome.pageAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

Đặt tiêu đề cho hành động trên trang. Thông tin này xuất hiện trong chú thích về thao tác trên trang.

Thông số

  • chi tiết

    đối tượng

    • tabId

      số

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

    • tiêu đề

      chuỗi

      Chuỗi chú giải công cụ.

  • callback

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

    Chrome 67 trở lên

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 101 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

show()

Promise 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
): Promise<void>

Hiện thao tác trên trang. Thao tác trên trang sẽ xuất hiện bất cứ khi nào thẻ được chọn.

Thông số

  • tabId

    số

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

  • callback

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

    Chrome 67 trở lên

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 101 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

Sự kiện

onClicked

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

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

Thông số

  • callback

    hàm

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

    (tab: tabs.Tab) => void