browser_api

AutocompleteAPI

Browser APIs pertaining to search and autocomplete.

Kind: global class

autocompleteAPI.addObserver(observer)

Add an observer to be notified when a search’s autocomplete results have changed.

Kind: instance method of AutocompleteAPI

Param Type Description
observer AutocompleteResultChangedCallback Callback triggered when a search’s autocomplete result has changed.

autocompleteAPI.query(input, preventInlineAutocomplete)

Request the browser for a set of autocomplete matches for a user-specified search query. When results are available, all registered observers will be notified.

Kind: instance method of AutocompleteAPI

Param Type Description
input string String to request autocomplete results for.
preventInlineAutocomplete boolean Inform the browser that the autocomplete result should not contain inline matches. This should primarily be set to to true in cases such as the user deleted text from the search input.

autocompleteAPI.stop()

If an autocomplete query is ongoing, cancel the request. Note that there is no guarantee the ongoing request is cancelled before the registered observers are notified.

Kind: instance method of AutocompleteAPI

autocompleteAPI.openMatch(index, url, middleButton, altKey, ctrlKey, metaKey, shiftKey)

Attempt to navigate to a specific autocomplete match.

This is done via a browser API (rather than a simple href) because the browser may update the match URL with parameters that were not available when the match was generated. These are namely time-based parameters.

Kind: instance method of AutocompleteAPI

Param Type Description
index number Index of the match in autocomplete matches array.
url string URL of the match to open. This is redundant with index, but is used as a final check for stale/malicious results.
middleButton boolean Whether the user’s middle mouse button was pressed to navigate to the match. If true, will open the match in a new tab.
altKey boolean Whether the user’s Alt key was pressed when the match was selected.
ctrlKey boolean Whether the user’s Control key was pressed when the match was selected. If true, will open the match in a new tab (Windows or Linux), or will defer the click to the OS (macOS).
metaKey boolean Whether the user’s Meta key was pressed when the match was selected. If true, will open the match in a new tab (macOS), or will defer the click to the OS (Windows or Linux).
shiftKey boolean Whether the user’s Shift key was pressed when the match was selected. If true, will open the match in a new window.

AutocompleteAPI.AutocompleteClassification : object

Autocomplete matches contain text spans that should be classified according to the below list of styles. Each classification contains an offset into the text at which the classification starts and a bitmask of styles that should be applied to that section of text.

Style Description Value
None No style should be applied 0
URL The text is a URL 1 << 1
Match Match for the user's search term 1 << 2
Dim Helper or descriptive text 1 << 3

Kind: static typedef of AutocompleteAPI
Properties

Name Type Description
offset number Position in the text this classification starts.
style number Bitmask of styles to apply to this classification.

AutocompleteAPI.AutocompleteMatch : object

A single autocomplete match for a search query. Contains information on the match itself (e.g. the URL and text of the match) and details on how the match should be displayed to the user.

There is abundant documentation in Chromium (link below) on these details. Developers should read that documentation before using this API.

Kind: static typedef of AutocompleteAPI
See: https://github.com/chromium/chromium/blob/80.0.3987.0/components/omnibox/browser/autocomplete_match.h
Properties

Name Type Description
contents string The text to display for the autocomplete match.
contentsClass Array.<AutocompleteClassification> List of style classifications for the contents string.
description string Additional helper text for the match, e.g. a title or description.
descriptionClass Array.<AutocompleteClassification> List of style classifications for the description string.
destinationUrl string URL to navigate to when the user selects this match.
type string Type of the match result.
isSearchType boolean Whether the match type is a search result (as opposed to a URL).
fillIntoEdit string Text to display when this match is selected via arrow/tab keys.
inlineAutocompletion string Text to display after the user’s cursor while typing.
allowedToBeDefaultMatch boolean Whether the match can be the default match.

AutocompleteAPI.AutocompleteResultChangedCallback : function

Callback triggered when a search’s autocomplete results have changed.

Kind: static typedef of AutocompleteAPI

Param Type Description
result object Object containing the autocomplete result.
result.input string Search query which generated the result.
result.matches Array.<AutocompleteMatch> List of matches.