From 2c2df5ea01eb5cd8b9ea226b2869337e59c5fe3e Mon Sep 17 00:00:00 2001 From: Florian Merz Date: Thu, 11 Feb 2021 14:50:24 +0100 Subject: unslug pt-pt: move --- .../user_interface/browser_action/index.html | 50 +++ .../user_interface/browser_styles/index.html | 453 +++++++++++++++++++++ .../user_interface/context_menu_items/index.html | 51 +++ .../user_interface/devtools_panels/index.html | 62 +++ .../user_interface/extension_pages/index.html | 64 +++ .../webextensions/user_interface/index.html | 93 +++++ .../user_interface/notifications/index.html | 50 +++ .../user_interface/omnibox/index.html | 70 ++++ .../user_interface/options_pages/index.html | 64 +++ .../user_interface/page_actions/index.html | 50 +++ .../webextensions/user_interface/popups/index.html | 60 +++ .../user_interface/sidebars/index.html | 57 +++ 12 files changed, 1124 insertions(+) create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/browser_action/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/browser_styles/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/extension_pages/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/notifications/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/omnibox/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/options_pages/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/page_actions/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/popups/index.html create mode 100644 files/pt-pt/mozilla/add-ons/webextensions/user_interface/sidebars/index.html (limited to 'files/pt-pt/mozilla/add-ons/webextensions/user_interface') diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/browser_action/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/browser_action/index.html new file mode 100644 index 0000000000..c5da78003b --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/browser_action/index.html @@ -0,0 +1,50 @@ +--- +title: Botão da Barra de Ferramentas +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Ação_navegador +tags: + - Extensão da Web +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +--- +
{{AddonSidebar}}
+ +

Normalmente referido como uma ação do navegador, esta opção da interface do utilizador é um botão adicionado à barra de ferramentas do navegador. Os utilizadores clicam no botão para interagir com a sua extensão.
+

+ +

The toolbar button (browser action) is very like the address bar button (page action). For the differences, and guidance on when to use what, see Page actions and browser actions.

+ +

Especificar a ação do navegador

+ +

Define as propriedades da ação do navegador utilizando a chave browser_action em manifest.json:

+ +
"browser_action": {
+  "default_icon": {
+    "19": "button/geo-19.png",
+    "38": "button/geo-38.png"
+  },
+  "default_title": "Whereami?"
+}
+ +

The only mandatory key is default_icon.

+ +

There are two ways to specify a browser action: with or without a popup. If you don't specify a popup, when the user clicks the button an event is dispatched to the extension, which the extension listens for using browserAction.onClicked:

+ +
browser.browserAction.onClicked.addListener(handleClick);
+ +

If you specify a popup, the click event is not dispatched: instead, the popup is shown when the user clicks the button. The user is able to interact with the popup and it closes automatically when the user clicks outside it. See the Popup article for more details on creating and managing popups.

+ +

Note that your extension can have only one browser action.

+ +

You can change any of the browser action properties programmatically using the browserAction API.

+ +

Ícones

+ +

For details on how to create icons to use with your browser action, see Iconography in the Photon Design System documentation.

+ +

Exemplos

+ +

The webextensions-examples repository on GitHub contains two examples of extensions that implement browser actions:

+ + diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/browser_styles/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/browser_styles/index.html new file mode 100644 index 0000000000..bc2f1bd2da --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/browser_styles/index.html @@ -0,0 +1,453 @@ +--- +title: Estilos de navegador +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Estilos_de_navegador +tags: + - Extensões + - Extensões da Web + - Extras +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles +--- +
{{AddonSidebar}}
+ +

Certain user interface components - browser and page action popups, sidebars, and options pages - are specified by your extension in essentially the same way:

+ +
    +
  1. create an HTML file defining the structure of the UI element
    2. +
  2. add a manifest.json key (browser_action, page_action, sidebar_action, or options_ui) pointing to that HTML file.
    3. +
+ +

One of the challenges with this approach is styling the element in such a way that it fits in with the browser's own style. To help with this, the manifest.json keys include an extra optional property: browser_style. If this is included and set to true, then your document will get one or more extra stylesheets that will help make it look consistent with the browser's UI and with other extensions that use the browser_style property.

+ +

In Firefox, the stylesheet can be seen at chrome://browser/content/extension.css. The extra stylesheet at chrome://browser/content/extension-mac.css is also included on OS X.

+ +

Most styles are automatically applied, but some elements require you to add the non-​standard browser-style class to get their styling since Firefox 55, as detailed in the table below:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementoExemplo
<button> + 
+<button class="browser-style">Click me</button>{{non-standard_inline}}
+
+

<select>

+ 		+ 
+<select class="browser-style" name="select">
+  <option value="value1">Value 1</option>
+  <option value="value2" selected>Value 2</option>
+  <option value="value3">Value 3</option>
+</select>
+
<textarea> + 
+<textarea class="browser-style">Write here</textarea>
+
Parent of an <input> + 
+<div class="browser-style">
+  <input type="radio" id="op1" name="choices" value="op1">
+  <label for="op1">Option 1</label>
+
+  <input type="radio" id="op2" name="choices" value="op2">
+  <label for="op2">Option 2</label>
+</div>
+
+ +

Compatibilidade de navegador

+ + + +

{{Compat("webextensions.browser_style")}}

+ +

Componentes de Painel do Firefox

+ +
+

{{NonStandardBadge(1)}} Non-Standard
+ This feature is non-standard and only works in Firefox.

+
+ +

The chrome://browser/content/extension.css stylesheet also contains the styles for the Firefox Panel Components.

+ +

The legacy Firefox Style Guide documents proper usage.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementoExemplo
Cabeçalho + 
+<header class="panel-section panel-section-header">
+  <div class="icon-section-header"><img src="image.svg"/></div>
+  <div class="text-section-header">Header</div>
+</header>
+
Rodapé + 
+<footer class="panel-section panel-section-footer">
+  <button class="panel-section-footer-button">Cancel</button>
+  <div class="panel-section-footer-separator"></div>
+  <button class="panel-section-footer-button default">Confirm</button>
+</footer>
+
Separadores + 
+<div class="panel-section panel-section-tabs">
+  <button class="panel-section-tabs-button selected">Tab</button>
+  <div class="panel-section-tabs-separator"></div>
+  <button class="panel-section-tabs-button">Tab</button>
+  <div class="panel-section-tabs-separator"></div>
+  <button class="panel-section-tabs-button">Tab</button>
+</div>
+
Form + 
+<div class="panel-section panel-section-formElements">
+  <div class="panel-formElements-item">
+    <label for="name01">Label:</label>
+    <input type="text" value="Name" id="name01" />
+  </div>
+  <div class="panel-formElements-item">
+    <label for="picker01">Label:</label>
+    <select id="picker01">
+      <option value="value1" selected="true">Dropdown</option>
+      <option value="value2">List Item</option>
+      <option value="value3">List Item</option>
+    </select>
+  </div>
+  <div class="panel-formElements-item">
+    <label for="placeholder01">Label:</label>
+    <input type="text" placeholder="Placeholder" id="placeholder01" />
+    <button name="expander" class="expander"></button>
+  </div>
+</div>
+
Menu + 
+<div class="panel-section panel-section-list">
+  <div class="panel-list-item">
+    <div class="icon"></div>
+    <div class="text">List Item</div>
+    <div class="text-shortcut">Ctrl-L</div>
+  </div>
+
+  <div class="panel-list-item">
+    <div class="icon"></div>
+    <div class="text">List Item</div>
+    <div class="text-shortcut"></div>
+  </div>
+
+  <div class="panel-section-separator"></div>
+
+  <div class="panel-list-item disabled">
+    <div class="icon"></div>
+    <div class="text">Disabled List Item</div>
+    <div class="text-shortcut"></div>
+  </div>
+
+  <div class="panel-section-separator"></div>
+
+  <div class="panel-list-item">
+    <div class="icon"></div>
+    <div class="text">List Item</div>
+    <div class="text-shortcut"></div>
+  </div>
+
+  <div class="panel-list-item">
+    <div class="icon"></div>
+    <div class="text">List Item</div>
+    <div class="text-shortcut"></div>
+  </div>
+</div>
+
+ +

Exemplo

+ +

HTML

+ +
<header class="panel-section panel-section-header">
+  <div class="icon-section-header"><!-- An image goes here. --></div>
+  <div class="text-section-header">Header</div>
+</header>
+
+<div class="panel-section panel-section-list">
+  <div class="panel-list-item">
+    <div class="icon"></div>
+    <div class="text">List Item</div>
+    <div class="text-shortcut">Ctrl-L</div>
+  </div>
+
+  <div class="panel-list-item">
+    <div class="icon"></div>
+    <div class="text">List Item</div>
+    <div class="text-shortcut"></div>
+  </div>
+
+  <div class="panel-section-separator"></div>
+
+  <div class="panel-list-item disabled">
+    <div class="icon"></div>
+    <div class="text">Disabled List Item</div>
+    <div class="text-shortcut"></div>
+  </div>
+
+  <div class="panel-section-separator"></div>
+
+  <div class="panel-list-item">
+    <div class="icon"></div>
+    <div class="text">List Item</div>
+    <div class="text-shortcut"></div>
+  </div>
+
+  <div class="panel-list-item">
+    <div class="icon"></div>
+    <div class="text">List Item</div>
+    <div class="text-shortcut"></div>
+  </div>
+</div>
+
+<footer class="panel-section panel-section-footer">
+  <button class="panel-section-footer-button">Cancel</button>
+  <div class="panel-section-footer-separator"></div>
+  <button class="panel-section-footer-button default">Confirm</button>
+</footer>
+ + + +

Result

+ +

{{EmbedLiveSample("Example","640","360")}}

diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html new file mode 100644 index 0000000000..231a800bc3 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html @@ -0,0 +1,51 @@ +--- +title: Itens do menu de contexto +slug: >- + Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Itens_do_menu_de_contexto +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items +--- +
{{AddonSidebar}}
+ +
+

Essa opção da interface do utilizador adiciona um ou mais itens a um menu de contexto do navegador.

+ +

Example of content menu items added by a WebExtension, from the context-menu-demo example

+ +

You would use this option to expose features that are relevant to specific browser or web page contexts. For example, you could show features to open a graphic editor when the user clicks on an image or offer a feature to save page content when part of a page is selected. You can add plain menu items, checkbox items, radio button groups, and separators to menus. Once a context menu item has been added using {{WebExtAPIRef("contextMenus.create")}} it's displayed in all browser tabs, but you can hide it by removing it with {{WebExtAPIRef("contextMenus.remove")}}.

+ +

Especificar itens do menu de contexto

+ +

You manage context menu items programmatically, using the {{WebExtAPIRef("contextMenus")}} API. However, you need to request the contextMenus permission in your manifest.json to be able to take advantage of the API.

+ +
"permissions": ["contextMenus"]
+ +

You can then add (and update or delete) the context menu items in your extension's background script. To create a menu item you specify an id, its title, and the context menus it should appear on:

+ +
browser.contextMenus.create({
+  id: "log-selection",
+  title: browser.i18n.getMessage("contextMenuItemSelectionLogger"),
+  contexts: ["selection"]
+}, onCreated);
+ +

Your extension then listens for clicks on the menu items. The passed information about the item clicked, the context where the click happened, and details of the tab where the click took place can then be used to invoke the appropriate extension functionality.

+ +
browser.contextMenus.onClicked.addListener(function(info, tab) {
+  switch (info.menuItemId) {
+    case "log-selection":
+      console.log(info.selectionText);
+      break;
+    ...
+  }
+})
+ +

Exemplos

+ +

O repositório de wexemplos das Extensões da Web no GitHub, contém vários exemplos de extensões que utilizam os itens do menu de contexto:

+ + +
diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html new file mode 100644 index 0000000000..a2bc9921ad --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html @@ -0,0 +1,62 @@ +--- +title: Painéis das ferramentas de desenvolvimento +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/devtools_panels +tags: + - Extensões da Web + - Guía + - Interface do Utilizador + - Principiante +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels +--- +
{{AddonSidebar}}
+ +
+

Esta funcionalidade está disponível desde o Firefox 54.

+
+ +

Quando uma extensão fornece ferramentas que são úteis para os programadores, é possível adicionar uma IU para as mesmas para as ferramentas de desenvolvimento do navegador como um novo painel.

+ +

Simple example showing the addition of "My panel" to the Developer Tools tabs.

+ +

Especificar um painel de ferramentas de desenvolvimento

+ +

Um painél das ferramentas de desenvovlimento é adicionado utilizando a API devtools.panels, que precisa de ser executada a partir de uma página de devtools especial.

+ +

Adicione a páginas de devtools, incluindo a chave devtools_page na extensão de manifest.json e forneça a localização do ficheiro HTML da página na extensão:

+ +
"devtools_page": "devtools-page.html"
+ +

From the devtools page, call a script that will add the devtools panel:

+ +
<body>
+  <script src="devtools.js"></script>
+</body>
+ +

In the script, create the devtools panel by specifying the panel's title, icon, and HTML file that provides the panel's content:

+ +
function handleShown() {
+  console.log("panel is being shown");
+}
+
+function handleHidden() {
+  console.log("panel is being hidden");
+}
+
+browser.devtools.panels.create(
+  "My Panel",           // title
+  "icons/star.png",           // icon
+  "devtools/panel/panel.html"          // content
+).then((newPanel) => {
+  newPanel.onShown.addListener(handleShown);
+  newPanel.onHidden.addListener(handleHidden);
+});
+ +

The extension can now run code in the inspected window using devtools.inspectedWindow.eval() or by injecting a content script via the background script by passing a message. You can find more details on how to do this in Extending the developer tools.

+ +

Exemplos

+ +

The webextensions-examples repo on GitHub, contains several examples of extensions that use devtools panels:

+ + diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/extension_pages/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/extension_pages/index.html new file mode 100644 index 0000000000..4bf94b9653 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/extension_pages/index.html @@ -0,0 +1,64 @@ +--- +title: Páginas de extensão +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Paginas_de_extensão +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages +--- +
{{AddonSidebar()}}
+ +

Pode inclur páginas html na sua extensão para fornecer formulários, ajuda, ou qualquer outro conteúdo que a sua extensão precisar.

+ +

Example of a simple bundled page displayed as a detached panel.

+ +

These pages also get access to the same privileged JavaScript APIs that are available to your extension's background scripts.

+ +

Especificar páginas de extensão

+ +

You can include HTML files, and their associated CSS or JavaScript files, in your extension. The files can be included in the root or organized within meaningful sub-folders.

+ +
/my-extension
+    /manifest.json
+    /my-page.html
+    /my-page.js
+ +

Exibir páginas de extensão

+ +

There are two options for displaying extension pages: {{WebExtAPIRef("windows.create()")}} and {{WebExtAPIRef("tabs.create()")}}.

+ +

Using windows.create(), for example, you can open an HTML page into a detached panel (a window without the normal browser UI of address bar, bookmark bar, and alike) to create a dialog-like user experience:

+ +
var createData = {
+  type: "detached_panel",
+  url: "panel.html",
+  width: 250,
+  height: 100
+};
+var creating = browser.windows.create(createData);
+ +

When the window is no longer needed, it can be closed programmatically, for example, after the user clicks a button, by passing the id of the current window to {{WebExtAPIRef("windows.remove()")}}:

+ +
document.getElementById("closeme").addEventListener("click", function(){
+  var winId = browser.windows.WINDOW_ID_CURRENT;
+  var removing = browser.windows.remove(winId);
+});
+ +

Páginas de extensão e histório

+ +

By default, pages you open in this way will be stored in the user's history, just like normal web pages. If you don't want to have this behavior, use {{WebExtAPIRef("history.deleteUrl()")}} to remove the browser's record:

+ +
function onVisited(historyItem) {
+  if (historyItem.url == browser.extension.getURL(myPage)) {
+    browser.history.deleteUrl({url: historyItem.url});
+  }
+}
+
+browser.history.onVisited.addListener(onVisited);
+ +

To use the history API, you must request the "history" permission in your manifest.json file.

+ +

Desenho da página da Web

+ +

For details on how to design your web page's to match the style of Firefox, see the Photon Design System documentation.

+ +

Exemplos

+ +

The webextensions-examples repository on GitHub includes the window-manipulator example, which implements several of the options for creating windows.

diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/index.html new file mode 100644 index 0000000000..6ec29a7fcf --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/index.html @@ -0,0 +1,93 @@ +--- +title: Interface do utilizador +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador +tags: + - Interface do Utilizador + - Landing + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/user_interface +--- +
{{AddonSidebar}}
+ +

As extensões que utilizam as APIs de WebExtension são fornecidas com várias opções de interface do utilizador, e assim, as suas funcionalidades podem ficar disponíveis para o utilizador. Um resumo dessas opções é fornecido abaixo, com uma introdução mais detalhada para cada opção da interface do utilziador nesta secção .

+ +
+

For advice on using these UI components to create a great user experience in your extension, please see the User experience best practices article.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Opção de UIDescriçãoExemplo
Browser toolbar buttonA button on the browser toolbar that dispatches an event to the extension when clicked. By default, the button is visible in all tabs.Example of a WebExtension toolbar button
Browser toolbar button with a popupA popup on a button in the browser toolbar that opens when the button is clicked. The popup is defined in an HTML document that handles the user interaction.Example of a WebExtension toolbar button with a popup
Address bar buttonA button on the browser address bar that dispatches an event to the extension when clicked. By default, the button is hidden in all tabs.Example showing an address bar button (page action)
Address bar button with a popupA popup on a button in the browser address bar that opens when the button is clicked. The popup is defined in an HTML document that handles the user interaction.Example of a popup on the address bar button
Context menu itemsMenu items, checkboxes, and radio buttons on one or more of the browser's context menus. Also, menus can be structured by adding separators. When menu items are clicked, an event is dispatched to the extension.
Sidebar +

An HTML document displayed next to a web page, with the option for unique content per page. The sidebar is opened when the extension is installed, then obeys the user's sidebar visibility selection. User interaction within the sidebar is handled by its HTML document.

+ 		Example of a WebExtension's sidebar
Options pageA page that enables you to define preferences for your extension that your users can change. The user can access this page in the from the browser's add-ons manager.Example showing the options page content added in the favorite colors example.
Bundled web pagesUse web pages included in your extension to provide forms, help, or any other content required, within windows or tabs.Example of a simple bundled page displayed as a detached panel.
NotificationsTransient notifications displayed to the user through the underlying operating system's notifications mechanism. Dispatches an event to the extension when the user clicks a notification, or when a notification closes (either automatically or at the user's request).Example notification from a WebExtension
Address bar suggestionsOffer custom address bar suggestions when the user enters a keyword.Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions.
Developer tools panelsA tab with an associated HTML document that displays in the browser's developer tools.New panel tab in the Developer Tools tab bar
+ +

The following how-to guides provide step-by-step guidance to creating some of these user interface options:

+ + diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/notifications/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/notifications/index.html new file mode 100644 index 0000000000..5b38d4f29f --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/notifications/index.html @@ -0,0 +1,50 @@ +--- +title: Notificações +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Notificacoes +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Notifications +--- +
{{AddonSidebar}}
+ +
+

As notificações permitem-lhe comunicar a informação sobre a sua extensão ou o seu conteúdo utilizando o serviço de notificação do sistema operativo subjacente:

+ +

+ +

As notificações podem incluir uma chamada para ação para o utilizador, e o seu extra pode escutar o utilizador a clicar na notificação ou a notificação a fechar.

+ +

Especificar as notificações

+ +

Pode gerir as notificações programaticamente, utilizando a API {{WebExtAPIRef("notifications")}}. Para utilizar esta API deve solicitar a permissão de notifications no seu manifest.json:

+ +
"permissions": ["notifications"]
+ +

Depois, pode utilziar {{WebExtAPIRef("notifications.create")}} para criar as suas notificações, como neste exemplo de notify-link-clicks-i18n:

+ +
var title = browser.i18n.getMessage("notificationTitle");
+var content = browser.i18n.getMessage("notificationContent", message.url);
+browser.notifications.create({
+  "type": "basic",
+  "iconUrl": browser.extension.getURL("icons/link-48.png"),
+  "title": title,
+  "message": content
+});
+ +

Este código cria uma notificação com um ícone, título, e mensagem.

+ +

Se a notificação incluir uma chamada para ação, pode escutar o utilizador a clicar na notificação para chamar a ação para manipular a ação:

+ +
browser.notifications.onClicked.addListener(handleClick);
+
+ +

Se estiver a enviar chamadas para ação através das notificações, também irá querer definir a notificação opcional id, e assim, pode saber qual a chamada para ação que o utilizador selecionou.

+ +

Exemplos

+ +

O repositório dos exemplos da extensões da Web no GitHub, contém vários exemplos das extensões que utilizam creates notifications:

+ + +
diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/omnibox/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/omnibox/index.html new file mode 100644 index 0000000000..c0f9f41dca --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/omnibox/index.html @@ -0,0 +1,70 @@ +--- +title: Sugestões da barra de endereço +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Omnibox +tags: + - Extensões da Web + - Interface do Utilizador +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Omnibox +--- +
{{AddonSidebar()}}
+ +

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.

+ +

Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions.

+ +

This enables your extension to, for example, search a library of free ebooks or, as in the example above, a repository of code examples.

+ +

Especificando a personalização de omnibox

+ +

You tell your extension that it is going to customize the address bar suggestions by including the omnibox key and definition of the trigger keyword in its manifest.json file:

+ +
  "omnibox": { "keyword" : "cs" }
+ +

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:

+ +
browser.omnibox.setDefaultSuggestion({
+  description: `Search the firefox codebase
+    (e.g. "hello world" | "path:omnibox.js onInputChanged")`
+});
+ +

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:

+ +
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);
+});
+ +

If the extension set a default suggestion using {{WebExtAPIRef("omnibox.setDefaultSuggestion()")}}, then this will appear first in the drop-down.

+ +

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:

+ +
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;
+  }
+});
+ +

 

+ +

Exemplos

+ +

O repositório dos exemplos das extensões da Web no GitHub inclui o exemplo firefox-code-search que personaliza a barra de pesquisa.

diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/options_pages/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/options_pages/index.html new file mode 100644 index 0000000000..b3bee11990 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/options_pages/index.html @@ -0,0 +1,64 @@ +--- +title: Página de opções +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Options_pages +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Options_pages +--- +
{{AddonSidebar}}
+ +
+

Uma página de Opções permite-lhe definir as preferências para sua extensão que os seus utilizadores podem alterar. Os utilizadores podem aceder á página das opções para uma extensão a partir do do gestor de extras do navegador:

+ +

{{EmbedYouTube("02oXAcbUv-s")}}

+ +

The way users access the page, and the way it's integrated into the browser's user interface, will vary from one browser to another.

+ + + +

You can open the page programmatically by calling runtime.openOptionsPage().

+ +

Options pages have a Content Security Policy that restricts the sources from which they can load resources, and disallows some unsafe practices such as the use of eval(). See Content Security Policy for more details.

+ +

Especificar a página de opções

+ +

To create an options page, write an HTML file defining the page. This page can include CSS and JavaScript files, like a normal web page. This page, from the favourite-colour example, includes a JavaScript file:

+ +
<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8">
+  </head>
+
+<body>
+  <form>
+      <label>Favourite colour</label>
+      <input type="text" id="colour" >
+      <button type="submit">Save</button>
+  </form>
+  <script src="options.js"></script>
+</body>
+
+</html>
+ +

JavaScript em execução na página pode utilizar a API das Extensões da Web que o extra tem permissões para. Em particular, pode utilziar a APi de armazenamento para manter as preferências.

+ +

Package the page's files in your extension.

+ +

You also need to include the options_ui key in your manifest.json file, giving it the URL to the page.

+ +
"options_ui": {
+  "page": "options.html",
+  "browser_style": true
+},
+ +

Exemplos

+ +

The webextensions-examples repo on GitHub, contains several examples of extensions that use an options page:

+ + +
diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/page_actions/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/page_actions/index.html new file mode 100644 index 0000000000..7093d3355c --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/page_actions/index.html @@ -0,0 +1,50 @@ +--- +title: Botão da barra de endereço +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Acoes_pagina +tags: + - Extensões da Web + - Interface do Utilizador +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Page_actions +--- +
{{AddonSidebar}}
+ +

Normalmente referido como uma ação da página, esta opção da inteface do utilizador é um botão adicionado à barra de endereço do navegador. Os utilziadores clicam no botão para interagir com a sua extensão.

+ +

+ +

Use this button when a feature is only relevant for some web pages. By default, the address bar button is hidden in all browser tabs, and you call pageAction.show() and pageAction.hide() to show or hide it in specific tabs.

+ +

Compare to the toolbar button, which offers similar behavior but is used in situations where the extension's features are applicable to almost every web page.

+ +

Especificar a ação da página

+ +

You define the page action's properties using the page_action key in manifest.json:

+ +
"page_action": {
+  "browser_style": true,
+  "default_icon": {
+    "19": "button/geo-19.png",
+    "38": "button/geo-38.png"
+  },
+  "default_title": "Whereami?"
+}
+ +

The only mandatory key is default_icon.

+ +

There are two ways to specify a page action: with or without a popup. If you don't specify a popup, when the user clicks the button an event is dispatched to the extension, which the extension listens for using pageAction.onClicked:

+ +
browser.pageAction.onClicked.addListener(handleClick);
+ +

If you specify a popup, the click event is not dispatched: instead, the popup is shown when the user clicks the button. The user is able to interact with the popup and it closes automatically when the user clicks outside it. See the Popup article for more details on creating and managing popups.

+ +

Note that your extension can have one page action only.

+ +

You can change any of the page action properties programmatically using the pageAction API.

+ +

Exemplos

+ +

The webextensions-examples repo on GitHub, contains several examples of extensions that use page action:

+ + diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/popups/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/popups/index.html new file mode 100644 index 0000000000..6bbf3f7ce8 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/popups/index.html @@ -0,0 +1,60 @@ +--- +title: Janelas (Popups) +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Popups +tags: + - Extensions + - IU + - Interface do Utilizador + - Janela + - popup +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Popups +--- +
{{AddonSidebar}}
+ +
+

Uma janela (popup) é uma janela que está associada com um botão da barra de ferramentas ou botão da barra de endereço.

+ +

+ +

Quando o usuário clica no botão, a janela popup é exibida. Quando o usuário clica em qualquer lugar fora do popup, ele é fechado. O popup pode ser fechado via programação usando a função window.close() em um script sendo executado no popup. Entretanto, você não pode abrir o popup via programação a partir do código JavaScript da extensão: ele somente se abre em resposta a uma ação do usuário.

+ +

Você pode definir um atalho de teclado que abre o popup usando "_execute_browser_action" and "_execute_page_action". Veja a documentação da chave commands       no manifest.json.

+ +

Especificar uma janela

+ +

O popup é definido por um arquivo HTML, que pode incluir arquivos CSS e JavaScript, como uma página comum. Diferentemente de uma página comum, o código JavaScript pode usar todos os WebExtension APIs que a extensão tem permissions .

+ +

O documento do popup é carregado toda vez que ele é exibido, e descarregado quando o popup é fechado.

+ +

O arquivo HTML é incluído na extensão e especificado como parte do  browser_action ou chave page_action por "default_popup" no arquivo manifest.json:

+ +
  "browser_action": {
+    "default_icon": "icons/beasts-32.png",
+    "default_title": "Beastify",
+    "default_popup": "popup/choose_beast.html"
+  }
+ +

You can ask the browser to include a stylesheet in your popup that will make it look consistent with the browser's UI. To do this, include "browser_style": true in the browser_action or page_action key.

+ +

Popups have a Content Security Policy that restricts the sources from which they can load resources, and disallows some unsafe practices such as the use of eval(). See Content Security Policy for more details on this.

+ +

Depurar janelas

+ +

You can debug a popup's markup and JavaScript using the Add-on Debugger, but you'll need to turn on the Disable popup auto hide feature to prevent popups from hiding when you click outside them. Read about debugging popups.

+ +

Redimensionar janelas

+ +

Popups resize automatically to fit their content. The algorithm for this may differ from one browser to another.

+ +

In Firefox, the size is calculated just before the popup is shown, and at most 10 times per second after DOM mutations. For strict mode documents, the size is calculated based on the layout size of the <body> element. For quirks mode, it's the <html> element. Firefox calculates the preferred width of the contents of that element, reflows it to that width, and then resizes so there's no vertical scrolling. It will grow to a size of 800x600 pixels at most if that fits on the user's screen. If the user moves the extension's button to the menu or it appears in the toolbar overflow, then the popup appears inside the menu's panel and is given a fixed width.

+ +

No Firefox Android 57, popup é mostrada como uma página normal num novo separador.

+ +

Desenho de janela

+ +

Para obter detalhes sobre como desenhar a sua janela (popup) da página da Web para combinar com o estilo do Firefox, consulte a documentação Photon Design System.

+ +

Exemplos

+ +

The webextensions-examples  repository on GitHub includes the beastify example which implements a browser action with a popup.

+
diff --git a/files/pt-pt/mozilla/add-ons/webextensions/user_interface/sidebars/index.html b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/sidebars/index.html new file mode 100644 index 0000000000..2cfa1800a7 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/user_interface/sidebars/index.html @@ -0,0 +1,57 @@ +--- +title: Barras laterais +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Barras_laterais +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Sidebars +--- +
{{AddonSidebar}}
+ +
+

 

+ +

Uma barra lateral é um painel que é exibido no lado esquerdo da janela do navegador, ao lado da página da Web. O navegador fornece uma IU que permite ao utilizador ver as barras laterais atualmente disponíveis e selecionar uma barra lateral para exibir. Por exemplo, o Firefox tem um menu 'Ver -> Barra lateral'. Apenas pode ser exibida uma barra lateral de cada vez, e essa barra lateral será exibida para todos os separadores e todas as janelas do navegador.

+ +

O navegador poderá incluir uma série de barras laterais integradas. Por exemplo, o Firefox inclui uma barra lateral para interagir com marcadores:

+ +

Using the sidebar_action manifest.json key, an extension can add its own sidebar to the browser. It will be listed alongside the built-in sidebars, and the user will be able to open it using the same mechanism as for the built-in sidebars.

+ +

Like a browser action popup, you specify the sidebar's contents as an HTML document. When the user opens the sidebar, its document is loaded into every open browser window. Each window gets its own instance of the document. When new windows are opened, they get their own sidebar documents as well.

+ +

You can set a document for a particular tab using the {{WebExtAPIRef("sidebarAction.setPanel()")}} function. A sidebar can figure out which window it belongs to using the {{WebExtAPIRef("windows.getCurrent()")}} API:

+ +
// sidebar.js
+browser.windows.getCurrent({populate: true}).then((windowInfo) => {
+  myWindowId = windowInfo.id;
+});
+ +

This is useful if a sidebar wants to display different content for different windows. For an example of this, see the "annotate-page" example.

+ +

Sidebar documents get access to the same set of privileged JavaScript APIs that the extension's background and popup scripts get. They can get direct access to the background page (unless the sidebar belongs to incognito mode window) using {{WebExtAPIRef("runtime.getBackgroundPage()")}}, and can interact with content scripts or native applications using messaging APIs like {{WebExtAPIRef("tabs.sendMessage()")}} and {{WebExtAPIRef("runtime.sendNativeMessage()")}}.

+ +

Sidebar documents are unloaded when their browser window is closed or when the user closes the sidebar. This means that unlike background pages, sidebar documents don't stay loaded all the time, but unlike browser action popups, they stay loaded while the user interacts with web pages.

+ +

When an extension that defines a sidebar is first installed, its sidebar will be opened automatically. This is intended to help the user understand that the extension includes a sidebar. Note that it's not possible for extension to open sidebars programmatically: sidebars can only be opened by the user.

+ +

Especificar barras laterais

+ +

To specify a sidebar, define the default document with the sidebar_action manifest.json key, alongside a default title and icon:

+ +
"sidebar_action": {
+  "default_title": "My sidebar",
+  "default_panel": "sidebar.html",
+  "default_icon": "sidebar_icon.png"
+}
+ +

You can change the title, panel, and icon programmatically using the {{WebExtAPIRef("sidebarAction")}} API.

+ +

Title and icon are shown to the user in any UI provided by the browser to list sidebars, such as the "View > Sidebar" menu in Firefox.

+ +

Exemplo

+ +

O repositório de exemplos das extensões da Web no GitHub, contém vários exemplos de extensões que utilizam a barra lateral:

+ + +
-- cgit v1.2.3-54-g00ecf