Các tiện ích Manifest V2 đã bị gỡ khỏi Cửa hàng Chrome trực tuyến vào ngày 31 tháng 8 năm 2026. Hãy di chuyển tiện ích của bạn sang Manifest V3 để người dùng có thể sử dụng lại tiện ích.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

chrome.browserAction

refresh date: 2026-09-25 robots: noindex

Mô tả

Sử dụng thao tác trên 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, một 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 một hành động của trình duyệt. Cửa sổ bật lên nằm bên dưới biểu tượng.

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ì hành động trên trình duyệt.

Tệp kê khai

Đăng ký thao tác 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 biểu tượng có kích thước bất kỳ để sử dụng trong Chrome. Chrome sẽ chọn biểu tượng gần nhất và điều chỉnh tỷ lệ cho phù hợp để lấp đầy không gian 16 dip. Tuy nhiên, nếu không cung cấp kích thước chính xác, 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ờ.

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. Đ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 không cần phải làm gì thêm để cung cấp các biểu tượng khác!

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

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

Một thao tác trên trình duyệt có thể có 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 dip (pixel không phụ thuộc vào thiết bị). Các biểu tượng lớn hơn sẽ được đổi kích thước cho vừa, nhưng để có kết quả tốt nhất, hãy sử dụng biểu tượng hình vuông 16 dip.

Bạn có thể đặt biểu tượng theo hai cách: sử dụng hình ảnh tĩnh hoặc sử dụng phần tử canvas HTML5. Việc sử dụng hình ảnh tĩnh sẽ dễ dàng hơn cho các ứng dụng đơn giản, nhưng bạn có thể tạo giao diện người dùng linh động hơn (chẳng hạn như ảnh động mượt mà) bằng cách sử dụ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. Đối với tiện ích chưa đóng gói, hình ảnh phải ở định dạng PNG.

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

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

Để đặt thành phần chú thích, hãy sử dụng trường default_title của browser_action trong tệp kê khai hoặc gọi phương thức browserAction.setTitle. Bạn có thể chỉ định chuỗi theo ngôn ngữ cho trường default_title; hãy xem phần Quốc tế hoá để biết thông tin chi tiết.

Huy hiệu

Thao tác trên 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 lớp trên biểu tượng). Huy hiệu giúp bạn dễ dàng cập nhật thao tác trên 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.

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

Đặt văn bản và màu sắc của huy hiệu bằng cách sử dụng lần lượt browserAction.setBadgeText và browserAction.setBadgeBackgroundColor.

Nếu một hành động của 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. 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à tự động điều chỉnh kích thước cho phù hợp 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 trên trình duyệt, hãy tạo một 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 browser_action trong manifest hoặc gọi phương thức browserAction.setPopup.

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

Ví dụ

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

Loại

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

disable()

Promise

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

Tắt thao tác trên trình duyệt cho một thẻ.

Thông số

tabId

number không bắt buộc

Mã nhận dạng của thẻ cần sửa đổi hành động của trình duyệt.
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 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()

Promise

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

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

Thông số

tabId

number không bắt buộc

Mã nhận dạng của thẻ cần sửa đổi hành động của trình duyệt.
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 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()

Promise

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

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

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

Giá trị trả về

Promise<extensionTypes.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()

Promise

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

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 quả
  
  chuỗi

Giá trị trả về

<string> hứa hẹn

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

Promise

chrome.browserAction.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 thao tác này trên trình duyệt.

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 quả
  
  chuỗi

Giá trị trả về

<string> hứa hẹn

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

Promise

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

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

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 quả
  
  chuỗi

Giá trị trả về

<string> hứa hẹn

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

Promise

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

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

Thông số

chi tiết

đối tượng
- màu
  
  string | ColorArray
  
  Một mảng gồm 4 số nguyên trong khoảng từ 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ã màu hex CSS; ví dụ: #FF0000 hoặc #F00 (màu đỏ). Hiển thị màu sắc ở độ mờ tối đa.
- tabId
  
  number không bắt buộc
  
  Giới hạn thay đổi khi một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ đóng.
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 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()

Promise

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

Đặt văn bản huy hiệu cho thao tác trên trình duyệt. Huy hiệu sẽ xuất hiện ở đầu biểu tượng.

Thông số

chi tiết

đối tượng
- tabId
  
  number không bắt buộc
  
  Giới hạn thay đổi khi một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ đóng.
- văn bản
  
  chuỗi không bắt buộc
  
  Bạn có thể truyền bao nhiêu ký tự cũng được, nhưng chỉ có khoảng 4 ký tự vừa với không gian. Nếu bạn 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.
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 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()

Promise

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

Đặt biểu tượng cho thao tác trên trình duyệt. Bạn có thể chỉ định biểu tượng dưới dạng đường dẫn đến tệp hình ảnh, 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 những 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
- 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 đượ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 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 dưới dạng từ điển, thì hình ảnh đượ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
  
  number không bắt buộc
  
  Giới hạn thay đổi khi một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ đóng.
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 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()

Promise

chrome.browserAction.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 hành động của trình duyệt.

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
  
  number không bắt buộc
  
  Giới hạn thay đổi khi một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ đóng.
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 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()

Promise

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

Đặt tiêu đề cho thao tác trên trình duyệt. Tiêu đề này xuất hiện trong chú thích.

Thông số

chi tiết

đối tượng
- tabId
  
  number không bắt buộc
  
  Giới hạn thay đổi khi một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ đóng.
- tiêu đề
  
  chuỗi
  
  Chuỗi mà thao tác trên trình duyệt sẽ hiển thị khi di chuột qua.
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 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 biểu tượng thao tác trên trình duyệt. Không kích hoạt nếu thao tác trên trình duyệt 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
```
- thẻ
  
  tabs.Tab

chrome.browserAction Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mô tả

Phạm vi cung cấp

Tệp kê khai

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

Biểu tượng

Chú thích

Huy hiệu

Cửa sổ bật lên

Mẹo

Ví dụ

Loại

TabDetails

Thuộc tính

Phương thức

disable()

Thông số

Giá trị trả về

enable()

Thông số

Giá trị trả về

getBadgeBackgroundColor()

Thông số

Giá trị trả về

getBadgeText()

Thông số

Giá trị trả về

getPopup()

Thông số

Giá trị trả về

getTitle()

Thông số

Giá trị trả về

setBadgeBackgroundColor()

Thông số

Giá trị trả về

setBadgeText()

Thông số

Giá trị trả về

setIcon()

Thông số

Giá trị trả về

setPopup()

Thông số

Giá trị trả về

setTitle()

Thông số

Giá trị trả về

Sự kiện

onClicked

Thông số

chrome.browserAction