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

chrome.browserAction

Nội dung mô tả

Sử dụng các thao tác của trình duyệt để đặt biểu tượng trên 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ũng có thể có phần chú thích, 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 thao tác trên trình duyệt. Một cửa sổ bật lên ở 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 thao tác trên trang thay vì thao tác trên trình duyệt.

Tệp kê khai

Đăng ký thao tác trên trình duyệt của bạn 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 và Chrome sẽ chọn biểu tượng gần nhất và điều chỉnh tỷ lệ biểu tượng đó thành kích thước phù hợp sao cho vừa với khoảng trống 16 điểm. Tuy nhiên, nếu không cung cấp kích thước chính xác, 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,5x hoặc 1,2x đ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ị biểu tượng từng thay đổi, thì bạn không cần phải làm gì thêm để cung cấp các biểu tượng khác nhau!

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

Hành động 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

Biểu tượng hành động của trình duyệt trong Chrome có chiều rộng và chiều cao tối đa là 16 điểm (pixel không phụ thuộc vào thiết bị). Các biểu tượng lớn hơn đượ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 2 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. Tuy nhiên, bạn có thể tạo giao diện người dùng động hơn (chẳng hạn như ảnh động 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. Đối với các tiện ích đã giải nén, 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 default_icon trong tệp kê khai hoặc gọi phương thức browserAction.setIcon.

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

Để đặt chú giải công cụ, 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 chuỗi dành riêng cho từng 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

Nếu muốn, các thao tác trên trình duyệt có thể hiển thị huy hiệu – một đoạn văn bản nằm trên biểu tượng. Huy hiệu giúp bạn dễ dàng cập nhật thao tác 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.

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

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

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. Cửa sổ bật lên có thể chứa bất kỳ nội dung HTML nào bạn thích và nó sẽ tự động được điều chỉ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 trên trình duyệt, hãy tạo tệp HTML chứa 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 phương thức browserAction.setPopup.

Mẹo

Để tạo ấn tượng tốt nhất về mặt hình ảnh, hãy làm theo các nguyên tắc sau:

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

Ví dụ

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

Loại

ColorArray

Loại

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

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

số không bắt buộc

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

Phương thức

disable()

Cam kết

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

Tắt thao tác của trình duyệt đối với 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 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ề

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

Cam kết

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

Bật thao tác 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 hành động 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ề

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

Cam kết

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

Cam kết

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ó thẻ nào được chỉ định thì văn bản huy hiệu không phải thẻ cụ thể 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ề

Hứa hẹn<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()

Cam kết

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ề

Hứa hẹn<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()

Cam kết

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ề

Hứa hẹn<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()

Cam kết

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 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à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 cho 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ề

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

Cam kết

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

Đặt văn bản huy hiệu cho hành động của trình duyệt. Huy hiệu này xuất hiện ở phía trên cùng của 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 cho 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ỉ có khoảng 4 ký tự có thể vừa với khoảng trống. Nếu một chuỗi trống ('') được truyền, 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 của thẻ đã chỉ định sẽ bị xoá và chuyển thành văn bản huy hiệu chung theo mặc định.
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ề

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

Cam kết

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

Đặt biểu tượng cho tác vụ của trình duyệt. Bạn có thể chỉ định biểu tượng làm đường dẫn đến một tệp hình ảnh, dưới dạng dữ liệu pixel từ một phần tử canvas hoặc từ điển của một trong những 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
- 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} 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, thì hình ảnh 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}'
- path
  
  chuỗi|đố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, thì hình ảnh 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ố không bắt buộc
  
  Giới hạn thay đổi cho 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ề

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

Cam kết

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

Đặt tài liệu HTML đượ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.

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 chính sách này thành chuỗi trống (''), thì 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 cho 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ề

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

Cam kết

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

Đặt tiêu đề cho hành động trên trình duyệt. Tiêu đề này 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 cho thời điểm một thẻ cụ thể được chọn. Tự động đặt lại khi thẻ bị đóng.
- title
  
  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ề

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 nhấp vào biểu tượng hành động của 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
```
- tab
  
  tabs.Tab

chrome.browserAction

Nội dung 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ú 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ố