chrome.pageAction

Mô tả

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

Phạm vi cung cấp

≤ MV2

Một số ví dụ:

  • Đăng ký nhận nguồn cấp dữ liệu RSS của trang này
  • Tạo một 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 tượng trưng cho một thao tác trên trang cho phép bạn đăng ký nhận RSS nguồn cấp dữ liệu cho trang hiện tại.

Các thao tác đối với trang bị ẩn 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ý theo dõi nguồn cấp dữ liệu cho trang hiện tại:

Hãy cân nhắc sử dụng một thao tác trên trình duyệt để người dùng luôn có thể tương tác với tiện ích.

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

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

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

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

Giống như hành động trên trình duyệt, hành động trên trang cũng có thể có biểu tượng, chú thích và cửa sổ bật lên; thì họ không thể có huy hiệu, Tuy nhiên. Ngoài ra, các hành động trên trang có thể chuyển sang màu xám. Bạn có thể tìm thấy thông tin về các biểu tượng, các chú thích 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 làm cho một tác vụ trên trang xuất hiện và chuyển sang màu xám bằng cách sử dụng pageAction.show và pageAction.hide. Theo mặc định, một tác vụ trên trang sẽ chuyển sang màu xám. Khi hiển thị biểu tượng, bạn chỉ định thẻ nơi biểu tượng sẽ xuất hiện. Biểu tượng này vẫn hiển thị cho đến khi thẻ bị đóng hoặc bắt đầu hiển thị một URL khác (ví dụ: vì người dùng nhấp vào một liên kết).

Mẹo

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

  • Hãy sử dụng các thao tác trên trang cho những tính năng chỉ có ý nghĩa với một vài trang.
  • Không sử dụng thao tác trên trang cho những tính năng có ý nghĩa với hầu hết các trang. Sử dụng các thao tác trên trình duyệt thay thế.
  • Không liên tục tạo ảnh động cho biểu tượng. Điều đó thật khó chịu.

Loại

ImageDataType

Dữ liệu về 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

    số không bắt buộc

    Mã nhận dạng 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 cụ thể đối với thẻ sẽ được trả về.

Phương thức

getPopup()

Lời hứa 
chrome.pageAction.getPopup(
  details: TabDetails,
  callback?: function,
)

Lấy tài liệu html được đặt làm cửa sổ bật lên cho tác vụ trang này.

Tham số

  • chi tiết

    TabDetails

  • số gọi lại

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

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

    (result: string) => void

    • kết quả

      string

Giá trị trả về

  • Cam kết<string>

    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()

Lời hứa 
chrome.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Lấy tiêu đề của hành động trên trang.

Tham số

  • chi tiết

    TabDetails

  • số gọi lại

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

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

    (result: string) => void

    • kết quả

      string

Giá trị trả về

  • Cam kết<string>

    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()

Lời hứa 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
)

Ẩn hành động trên trang. Các tác vụ ẩn trên trang vẫn xuất hiện trong thanh công cụ Chrome nhưng có màu xám.

Tham số

  • tabId

    số

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

  • số gọi lại

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

    Chrome 67 trở lên

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

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    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()

Lời hứa 
chrome.pageAction.setIcon(
  details: object,
  callback?: function,
)

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

Tham số

  • chi tiết

    đối tượng

    • iconIndex

      số không bắt buộc

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

    • dữ liệu hình ảnh

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

      Đối tượng ImageData hoặc từ điển {size -> ImageData} biểu thị biểu tượng cần đặt. Nếu biểu tượng được chỉ định làm 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ố 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 | đối tượng không bắt buộc

      Đường dẫn hình ảnh tương đối hoặc từ điển {size -> Tương đối đường dẫn hình ảnh} trỏ đến biểu tượng cần đặt. Nếu biểu tượng được chỉ định làm 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ố 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ố

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

  • số gọi lại

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

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

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    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()

Lời hứa 
chrome.pageAction.setPopup(
  details: object,
  callback?: function,
)

Đặt tài liệu HTML thành 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.

Tham số

  • chi tiết

    đối tượng

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

      string

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

    • tabId

      số

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

  • số gọi lại

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

    Chrome 67 trở lên

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

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    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()

Lời hứa 
chrome.pageAction.setTitle(
  details: object,
  callback?: function,
)

Đặt tiêu đề của hành động trên trang. Thông tin này được hiển thị trong chú giải công cụ trên hành động trên trang.

Tham 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 đề

      string

      Chuỗi chú thích.

  • số gọi lại

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

    Chrome 67 trở lên

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

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    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()

Lời hứa 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
)

Cho thấy hành động trên trang. Hành động trên trang sẽ hiển thị bất cứ khi nào thẻ được chọn.

Tham số

  • tabId

    số

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

  • số gọi lại

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

    Chrome 67 trở lên

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

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    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 một biểu tượng hành động trên trang. Sự kiện này sẽ không kích hoạt nếu hành động trên trang có cửa sổ bật lên.

Tham số

  • số gọi lại

    hàm

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

    (tab: tabs.Tab) => void