chrome.omnibox

Mô tả

API thanh địa chỉ cho phép bạn đăng ký từ khoá bằng thanh địa chỉ của Google Chrome, còn được gọi là thanh địa chỉ.

Ảnh chụp màn hình cho thấy các nội dung đề xuất có liên quan đến từ khoá "Tìm kiếm Chromium"

Khi người dùng nhập từ khoá của tiện ích mở rộng, người dùng bắt đầu duy nhất tương tác với tiện ích. Mỗi thao tác nhấn phím sẽ được gửi đến tiện ích của bạn và bạn có thể cung cấp các đề xuất tương ứng.

Các đề xuất có thể được định dạng phong phú theo nhiều cách. Khi người dùng chấp nhận đề xuất, tiện ích của bạn sẽ được thông báo và có thể thực hiện hành động.

Tệp kê khai

Bạn phải khai báo các khoá sau trong tệp kê khai để sử dụng API này.

"omnibox"

Bạn phải đưa trường "omnibox.keyword" vào tệp kê khai để sử dụng API thanh địa chỉ. Bạn cũng phải chỉ định biểu tượng 16 x 16 pixel, biểu tượng này sẽ được hiển thị trong thanh địa chỉ khi đề xuất mà người dùng vào chế độ từ khoá.

Ví dụ:

{
  "name": "Aaron's omnibox extension",
  "version": "1.0",
  "omnibox": { "keyword" : "aaron" },
  "icons": {
    "16": "16-full-color.png"
  },
  "background": {
    "persistent": false,
    "scripts": ["background.js"]
  }
}

Ví dụ

Để dùng thử API này, hãy cài đặt ví dụ về API thanh địa chỉ từ chrome-extension-samples kho lưu trữ.

Loại

DefaultSuggestResult

Kết quả đề xuất.

Thuộc tính

  • description

    string

    Văn bản xuất hiện trong trình đơn thả xuống của URL. Có thể chứa mã đánh dấu kiểu XML để định kiểu. Các thẻ được hỗ trợ là "url" (đối với URL cố định), "match" (để đánh dấu văn bản khớp với truy vấn của người dùng) và "làm mờ" (đối với văn bản trợ giúp tối). Các kiểu có thể được lồng vào nhau, ví dụ: kết quả phù hợp bị làm mờ.

DescriptionStyleType

Chrome 44 trở lên

Loại kiểu.

Enum

"url"

"match"

"giảm độ sáng"

OnInputEnteredDisposition

Chrome 44 trở lên

Vị trí cửa sổ cho truy vấn thanh địa chỉ. Bạn nên sử dụng bối cảnh này để hiển thị kết quả. Ví dụ: nếu lệnh thanh địa chỉ điều hướng đến một URL nhất định, thì một vị trí của "newForegroundTab" có nghĩa là thao tác điều hướng sẽ diễn ra trong thẻ mới được chọn.

Enum

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Kết quả đề xuất.

Thuộc tính

  • nội dung

    string

    Văn bản được đưa vào thanh URL và được gửi tới tiện ích khi người dùng chọn mục nhập này.

  • có thể xoá

    boolean không bắt buộc

    Chrome 63 trở lên

    Liệu người dùng có thể xoá kết quả đề xuất hay không.

  • description

    string

    Văn bản xuất hiện trong trình đơn thả xuống của URL. Có thể chứa mã đánh dấu kiểu XML để định kiểu. Các thẻ được hỗ trợ là "url" (đối với URL cố định), "match" (để đánh dấu văn bản khớp với truy vấn của người dùng) và "làm mờ" (đối với văn bản trợ giúp tối). Các kiểu có thể được lồng vào nhau, ví dụ: kết quả phù hợp bị làm mờ. Bạn phải thoát 5 thực thể được xác định trước để hiển thị chúng dưới dạng văn bản: stackoverflow.com/a/1091953/89484

Phương thức

setDefaultSuggestion()

Lời hứa 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
)

Thiết lập nội dung mô tả và kiểu cho đề xuất mặc định. Đề xuất mặc định là văn bản được hiển thị trong hàng đề xuất đầu tiên bên dưới thanh URL.

Tham số

  • đề xuất

    DefaultSuggestResult

    Một phần đối tượng OfferResult không có "content" .

  • số gọi lại

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

    Chrome 100 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 100 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

Sự kiện

onDeleteSuggestion

Chrome 63 trở lên 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

Người dùng đã xoá một kết quả được đề xuất.

Tham số

  • số gọi lại

    hàm

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

    (text: string) => void

    • văn bản

      string

onInputCancelled

chrome.omnibox.onInputCancelled.addListener(
  callback: function,
)

Người dùng đã kết thúc phiên nhập từ khoá mà không chấp nhận thông tin nhập.

Tham số

  • số gọi lại

    hàm

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

    () => void

onInputChanged

chrome.omnibox.onInputChanged.addListener(
  callback: function,
)

Người dùng đã thay đổi nội dung nhập vào thanh địa chỉ.

Tham số

  • số gọi lại

    hàm

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

    (text: string, suggest: function) => void

    • văn bản

      string

    • đề xuất

      hàm

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

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult[]

        Mảng gồm các kết quả đề xuất

onInputEntered

chrome.omnibox.onInputEntered.addListener(
  callback: function,
)

Người dùng đã chấp nhận nội dung được nhập vào thanh địa chỉ.

Tham số

onInputStarted

chrome.omnibox.onInputStarted.addListener(
  callback: function,
)

Người dùng đã bắt đầu phiên nhập từ khoá bằng cách nhập từ khoá của tiện ích. Lệnh này được đảm bảo gửi chính xác một lần cho mỗi phiên nhập và trước mọi sự kiện onInputChanged

Tham số

  • số gọi lại

    hàm

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

    () => void