1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
---
title: Sugestões da barra de endereço
slug: Mozilla/Add-ons/WebExtensions/user_interface/Omnibox
tags:
- Extensões da Web
- Interface do Utilizador
translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Omnibox
original_slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Omnibox
---
<div>{{AddonSidebar()}}</div>
<p>Using the {{WebExtAPIRef("omnibox")}} API, extensions can customize the suggestions offered in the browser address bar's drop-down when the user enters a keyword.</p>
<p><img alt="Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions." src="https://mdn.mozillademos.org/files/15749/omnibox_example_small.png" style="display: block; height: 232px; margin-left: auto; margin-right: auto; width: 350px;"></p>
<p>This enables your extension to, for example, search a library of free ebooks or, as in the example above, a repository of code examples.</p>
<h2 id="Especificando_a_personalização_de_omnibox">Especificando a personalização de omnibox</h2>
<p>You tell your extension that it is going to customize the address bar suggestions by including the <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/omnibox">omnibox</a> key and definition of the trigger keyword in its <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> file:</p>
<pre class="brush: json line-numbers language-json"> "omnibox": { "keyword" : "cs" }</pre>
<p>In the extension's background JavaScript file, using {{WebExtAPIRef("omnibox.setDefaultSuggestion()")}}, you can optionally define the first suggestion to be displayed in the address bar drop-down. Use this to provide a hint on how to use the feature:</p>
<pre class="brush: js line-numbers language-js">browser.omnibox.setDefaultSuggestion({
description: `Search the firefox codebase
(e.g. "hello world" | "path:omnibox.js onInputChanged")`
});</pre>
<p>You can then add the code to provide the customized content by listening for {{WebExtAPIRef("omnibox.onInputStarted")}}, which is dispatched when the user has typed the keyword and a space, and {{WebExtAPIRef("omnibox.onInputChanged")}}, which is dispatched whenever the user updates the address bar entry. You can then populate the suggestions, in this case building a search of https://searchfox.org/mozilla-central using the term entered by the user:</p>
<pre class="brush: js">browser.omnibox.onInputChanged.addListener((text, addSuggestions) => {
let headers = new Headers({"Accept": "application/json"});
let init = {method: 'GET', headers};
let url = buildSearchURL(text);
let request = new Request(url, init);
fetch(request)
.then(createSuggestionsFromResponse)
.then(addSuggestions);
});</pre>
<p>If the extension set a default suggestion using {{WebExtAPIRef("omnibox.setDefaultSuggestion()")}}, then this will appear first in the drop-down.</p>
<p>The extension can then listen for the user clicking one of the suggestions, using {{WebExtAPIRef("omnibox.onInputEntered")}}. If the default suggestion is clicked the user's custom term is returned, otherwise the suggestion's string is returned. This also passes information on the user's browser preferences for handling new links. In the code below the user's custom term is used to create a search, otherwise the suggested URL is opened:</p>
<pre class="brush: js">browser.omnibox.onInputEntered.addListener((text, disposition) => {
let url = text;
if (!text.startsWith(SOURCE_URL)) {
// Update the url if the user clicks on the default suggestion.
url = `${SEARCH_URL}?q=${text}`;
}
switch (disposition) {
case "currentTab":
browser.tabs.update({url});
break;
case "newForegroundTab":
browser.tabs.create({url});
break;
case "newBackgroundTab":
browser.tabs.create({url, active: false});
break;
}
});</pre>
<p> </p>
<h2 id="Exemplos">Exemplos</h2>
<p>O repositório dos <a href="https://github.com/mdn/webextensions-examples">exemplos das extensões da Web</a> no GitHub inclui o exemplo <a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/firefox-code-search">firefox-code-search</a> que personaliza a barra de pesquisa.</p>
|
