Trang này được dịch bởi Cloud Translation API.

chrome.browserAction

Mô tả

Sử dụng các thao tác của trình duyệt để đặt biểu tượng vào thanh công cụ chính của Google Chrome, ở bên phải thanh địa chỉ. Ngoài biểu tượng, thao tác trên trình duyệt có thể có chú giải công cụ, huy hiệu và cửa sổ bật lên.

Phạm vi cung cấp

&leq; MV2

Trong hình sau, hình vuông nhiều màu ở bên phải thanh địa chỉ là biểu tượng cho hành động của trình duyệt. Một cửa sổ bật lên ở bên dưới biểu tượng này.

Nếu bạn muốn tạo một biểu tượng không phải lúc nào cũng hoạt động, hãy sử dụng hành động trên trang thay vì trình duyệt hành động.

Tệp kê khai

Đăng ký thao tác của bạn trên trình duyệt trong tệp kê khai tiện ích như sau:

{
  "name": "My extension",
  ...
  "browser_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
  },
  ...
}

Bạn có thể cung cấp mọi biểu tượng có kích thước để sử dụng trong Chrome, sau đó Chrome sẽ chọn biểu tượng có kích thước và tỷ lệ gần nhất nó đến kích thước phù hợp để lấp đầy khoảng trống 16-giọt. Tuy nhiên, nếu kích thước chính xác không được cung cấp, giá trị này việc điều chỉnh tỷ lệ có thể làm cho biểu tượng mất chi tiết hoặc trông mờ.

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. Đ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ì nữa để cung cấp các biểu tượng khác nhau!

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

{
  "name": "My extension",
  ...
  "browser_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

Một thao tác trên trình duyệt có thể có một biểu tượng, chú giải công cụ, huy hiệu và cửa sổ bật lên.

Biểu tượng

Các biểu tượng thao tác trên trình duyệt trong Chrome có chiều rộng và chiều cao là 16 pixel (pixel độc lập với thiết bị). Lớn hơn các biểu tượng được đổi kích thước cho phù hợp, nhưng để có kết quả tốt nhất, hãy sử dụng biểu tượng hình vuông 16 nhúng.

Bạn có thể đặt biểu tượng theo hai cách: sử dụng hình ảnh tĩnh hoặc phần tử canvas HTML5. Sử dụng hình ảnh tĩnh sẽ dễ dàng hơn đối với các ứng dụng đơn giản, nhưng bạn có thể tạo giao diện người dùng động hơn — chẳng hạn như hoạt ảnh mượt mà—bằng phần tử canvas.

Hình ảnh tĩnh có thể ở bất kỳ định dạng nào mà WebKit có thể hiển thị, bao gồm BMP, GIF, ICO, JPEG hoặc PNG. Cho tiện ích đã giải nén, hình ảnh phải ở định dạng PNG.

Để đặt biểu tượng này, hãy sử dụng trường default_icon của default_icon trong tệp kê khai hoặc gọi phương thức browserAction.setIcon.

Để hiển thị biểu tượng một cách chính xác khi mật độ pixel trên màn hình (tỷ lệ size_in_pixel / size_in_dip) là khác 1, thì biểu tượng có thể được xác định là một tập hợp hình ảnh với các kích thước khác nhau. Hình ảnh thực tế cho màn hình sẽ được chọn từ nhóm phù hợp nhất với kích thước pixel là 16 pixel. Bộ biểu tượng có thể chứa mọi thông số biểu tượng kích thước và Chrome sẽ chọn kích thước phù hợp nhất.

Để đặt chú thích, hãy sử dụng trường default_title của default_title trong tệp kê khai hoặc gọi phương thức browserAction.setTitle. Bạn có thể chỉ định các chuỗi dành riêng cho từng ngôn ngữ cho trường default_title; hãy xem nội dung Quốc tế hoá để biết thêm chi tiết.

Huy hiệu

Nếu muốn, thao tác của trình duyệt có thể hiển thị một huy hiệu – một đoạn văn bản được xếp chồng lên biểu tượng. Huy hiệu giúp bạn dễ dàng cập nhật hành động của trình duyệt để hiển thị một lượng nhỏ thông tin về trạng thái của tiện ích.

Do không gian hạn chế, huy hiệu chỉ được dài tối đa 4 ký tự.

Đặt văn bản và màu sắc của huy hiệu bằng browserAction.setBadgeText và browserAction.setBadgeBackgroundColor.

Nếu một thao tác trên trình duyệt có cửa sổ bật lên, thì cửa sổ bật lên sẽ xuất hiện khi người dùng nhấp vào biểu tượng của tiện ích. Chiến lược phát hành đĩa đơn bật lên có thể chứa bất kỳ nội dung HTML nào bạn thích và cửa sổ bật lên được tự động định kích thước cho vừa với nội dung. Cửa sổ bật lên không được nhỏ hơn 25x25 và không được lớn hơn 800x600.

Để thêm cửa sổ bật lên vào thao tác của trình duyệt, hãy tạo tệp HTML có nội dung của cửa sổ bật lên. Chỉ định Tệp HTML trong trường default_popup của default_popup trong tệp kê khai hoặc gọi browserAction.setPopup.

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 trình duyệt cho các tính năng có ý nghĩa trên hầu hết các trang.
Không sử dụng các thao tác trên trình duyệt cho các tính năng chỉ có ý nghĩa với một vài trang. Sử dụng trang actions.
Hãy sử dụng các biểu tượng lớn, nhiều màu sắc để tận dụng tối đa không gian nhúng 16x16. Các biểu tượng thao tác trên trình duyệt sẽ có vẻ lớn hơn và nặng hơn một chút so với biểu tượng hành động trên trang.
Không tìm cách bắt chước biểu tượng trình đơn đơn sắc của Google Chrome. Cách đó không hoạt động tốt với giao diện và dù sao thì tiện ích cũng nên nổi bật.
Hãy sử dụng độ trong suốt alpha để thêm các cạnh mềm vào biểu tượng. Vì nhiều người sử dụng chủ đề, nên phải trông đẹp mắt trên nhiều màu nền.
Không liên tục tạo ảnh động cho biểu tượng. Điều đó thật khó chịu.

Ví dụ

Bạn có thể tìm thấy các ví dụ đơn giản về cách sử dụng các thao tác trên trình duyệt trong examples/api/browserAction thư mục. Để biết các ví dụ khác và để được trợ giúp xem mã nguồn, hãy xem phần Mẫu.

Loại

ColorArray

Loại

[số, số, số, số]

ImageDataType

Dữ liệu về pixel cho một hình ảnh. Phải là một đối tượng ImageData; ví dụ: qua 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

disable()

Lời hứa

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

Vô hiệu hoá thao tác trên trình duyệt 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 thao tác của trình duyệt.
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 88 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.

enable()

Lời hứa

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

Bật tác vụ trên trình duyệt cho một thẻ. Giá trị mặc định là bật.

Tham số

tabId

số không bắt buộc

Mã của thẻ mà bạn muốn sửa đổi thao tác của trình duyệt.
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 88 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.

getBadgeBackgroundColor()

Lời hứa

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

Lấy màu nền của thao tác trên trình duyệt.

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: ColorArray) => void
```
- kết quả
  
  ColorArray

Giá trị trả về

Promise<ColorArray>

Chrome 88 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.

getBadgeText()

Lời hứa

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

Lấy văn bản huy hiệu của hành động trên trình duyệt. Nếu không có tab nào được chỉ định, văn bản huy hiệu không dành riêng cho tab sẽ được trả về.

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 quả
  
  string

Giá trị trả về

Cam kết<string>

Chrome 88 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.

getPopup()

Lời hứa

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

Lấy tài liệu HTML được đặt làm cửa sổ bật lên cho thao tác này trên trình duyệt.

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 quả
  
  string

Giá trị trả về

Cam kết<string>

Chrome 88 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.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Lấy tiêu đề của hành động trên trình duyệt.

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 quả
  
  string

Giá trị trả về

Cam kết<string>

Chrome 88 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.

setBadgeBackgroundColor()

Lời hứa

chrome.browserAction.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 phạm vi 0 đến 255 tạo nên màu RGBA của huy hiệu. Cũng có thể là một chuỗi có giá trị màu hex CSS; ví dụ: #FF0000 hoặc #F00 (màu đỏ). Hiển thị màu ở độ mờ hoàn toàn.
- tabId
  
  số không bắt buộc
  
  Giới hạn thay đổi ở thời điểm một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ bị đóng.
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 88 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.

setBadgeText()

Lời hứa

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

Đặt văn bản huy hiệu cho thao tác của trình duyệt. Huy hiệu này sẽ xuất hiện ở phía trên 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 một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ bị đóng.
- văn bả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ào khoảng trống. Nếu truyền một chuỗi trống ('') thì văn bản huy hiệu sẽ bị xoá. Nếu bạn chỉ định tabId và text là rỗng, thì văn bản cho thẻ được chỉ định sẽ bị xoá và mặc định là văn bản huy hiệu chung.
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 88 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.browserAction.setIcon(
  details: object,
  callback?: function,
)

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

Tham số

chi tiết

đối tượng
- 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ị một biểu tượng cần đặt. Nếu biểu tượng được chỉ định làm từ điển, hình ảnh được sử dụng sẽ được chọn tùy 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ì một 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 một biểu tượng cần đặt. Nếu biểu tượng được chỉ định làm từ điển, hình ảnh được sử dụng sẽ được chọn tùy 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ì một 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 một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ bị đóng.
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 116 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.browserAction.setPopup(
  details: object,
  callback?: function,
)

Thiết lập để 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 thao tác của trình duyệt.

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ố không bắt buộc
  
  Giới hạn thay đổi ở thời điểm một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ bị đóng.
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 88 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.browserAction.setTitle(
  details: object,
  callback?: function,
)

Đặt tiêu đề cho hành động của trình duyệt. Tiêu đề 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 một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ bị đóng.
- tiêu đề
  
  string
  
  Chuỗi mà thao tác của trình duyệt sẽ hiển thị khi di chuột qua.
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 88 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.browserAction.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 trình duyệt. Không kích hoạt nếu hành động trên trình duyệt 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
```
- phím tab
  
  tabs.Tab

chrome.browserAction

Mô tả

Phạm vi cung cấp

Tệp kê khai

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

Biểu tượng

Chú giải công cụ

Huy hiệu

Cửa sổ bật lên

Mẹo

Ví dụ

Loại

ColorArray

Loại

ImageDataType

Loại

TabDetails

Thuộc tính

Phương thức

disable()

Tham số

Giá trị trả về

enable()

Tham số

Giá trị trả về

getBadgeBackgroundColor()

Tham số

Giá trị trả về

getBadgeText()

Tham số

Giá trị trả về

getPopup()

Tham số

Giá trị trả về

getTitle()

Tham số

Giá trị trả về

setBadgeBackgroundColor()

Tham số

Giá trị trả về

setBadgeText()

Tham số

Giá trị trả về

setIcon()

Tham số

Giá trị trả về

setPopup()

Tham số

Giá trị trả về

setTitle()

Tham số

Giá trị trả về

Sự kiện

onClicked

Tham số