Cómo diseñar la interfaz de usuario

La interfaz de usuario de la extensión debe ser útil y mínima. Al igual que las extensiones, la IU debe personalizar o mejorar la experiencia de navegación sin distraerla.

En esta guía, se exploran las funciones obligatorias y opcionales de la interfaz de usuario. Úsala para comprender cómo y cuándo implementar diferentes elementos de la IU dentro de una extensión.

Activa la extensión en todas las páginas

Usa un browser_action cuando las funciones de una extensión sean funcionales en la mayoría de las situaciones.

Registra la acción del navegador

El campo "browser_action" está registrado en el manifiesto.

{
  "name": "My Awesome browser_action Extension",
  ...
  "browser_action": {
    ...
  }
  ...
}

Si declaras "browser_action", el ícono se mantendrá coloreado, lo que indica que la extensión está disponible para los usuarios.

Agrega una insignia

Las insignias muestran un banner de color con hasta cuatro caracteres sobre el ícono del navegador. Solo pueden usarlas las extensiones que declaran "browser_action" en su manifiesto.

Usa insignias para indicar el estado de la extensión. En el ejemplo de Drink Water Event, se muestra una insignia con "ON" para mostrarle al usuario que configuró correctamente una alarma y no muestra nada cuando la extensión está inactiva.

Para configurar el texto de la insignia, llama a chrome.browserAction.setBadgeText. Para configurar el color del banner , llama a chrome.browserAction.setBadgeBackgroundColor.

chrome.browserAction.setBadgeText({text: 'ON'});
chrome.browserAction.setBadgeBackgroundColor({color: '#4688F1'});

Activa la extensión en páginas seleccionadas

Usa page_action cuando las funciones de una extensión solo estén disponibles en circunstancias definidas.

Declara la acción de la página

El campo "page_action" está registrado en el manifiesto.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    ...
  }
  ...
}

Si declaras "page_action", el ícono se coloreará solo cuando la extensión esté disponible para los usuarios; de lo contrario, se mostrará en escala de grises.

Define reglas para activar la extensión

Para definir reglas sobre cuándo se puede usar la extensión, llama a chrome.declarativeContent en el objeto de escucha runtime.onInstalled en una secuencia de comandos en segundo plano. La extensión de ejemplo Page action by URL establece una condición de que la URL debe incluir una "g". Si se cumple la condición, la extensión llama a declarativeContent.ShowPageAction().

chrome.runtime.onInstalled.addListener(function() {
  // Replace all rules ...
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    // With a new rule ...
    chrome.declarativeContent.onPageChanged.addRules([
      {
        // That fires when a page's URL contains a 'g' ...
        conditions: [
          new chrome.declarativeContent.PageStateMatcher({
            pageUrl: { urlContains: 'g' },
          })
        ],
        // And shows the extension's page action.
        actions: [ new chrome.declarativeContent.ShowPageAction() ]
      }
    ]);
  });
});

Habilita o inhabilita la extensión

Las extensiones que usan "page_action" pueden activarse y desactivarse de forma dinámica llamando a pageAction.show y pageAction.hide.

La extensión de ejemplo Mappy analiza una página web en busca de una dirección y muestra su ubicación en un mapa estático en la ventana emergente. Debido a que la extensión depende del contenido de la página, no puede declarar reglas para predecir qué páginas serán relevantes. En cambio, si se encuentra una dirección en una página, llama a pageAction.show para colorear el ícono y señalar que la extensión se puede usar en esa pestaña.

chrome.runtime.onMessage.addListener(function(req, sender) {
  chrome.storage.local.set({'address': req.address})
  chrome.pageAction.show(sender.tab.id);
  chrome.pageAction.setTitle({tabId: sender.tab.id, title: req.address});
});

Proporciona los íconos de la extensión

Las extensiones requieren al menos un ícono para representarlas. Proporciona íconos en formato PNG para obtener los mejores resultados visuales, aunque se acepta cualquier formato compatible con WebKit, incluidos BMP, GIF, ICO y JPEG.

Designa íconos de la barra de herramientas

Los íconos específicos de la barra de herramientas se registran en el "default_icon" campo bajo browser_action o page_action en el manifiesto. Se recomienda incluir varios tamaños para ajustar la escala del espacio de 16 dp. Como mínimo, se recomiendan los tamaños de 16x16 y 32x32.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    "default_icon": {
      "16": "extension_toolbar_icon16.png",
      "32": "extension_toolbar_icon32.png"
    }
  }
  ...
}

Todos los íconos deben ser cuadrados, ya que, de lo contrario, podrían distorsionarse. Si no se proporcionan íconos, Chrome agregará uno genérico a la barra de herramientas.

Crea y registra íconos adicionales

Incluye íconos adicionales en los siguientes tamaños para usos fuera de la barra de herramientas.

Registra los íconos en el manifiesto en el campo "icons".

{
  "name": "My Awesome Extension",
  ...
  "icons": {
    "16": "extension_icon16.png",
    "32": "extension_icon32.png",
    "48": "extension_icon48.png",
    "128": "extension_icon128.png"
  }
  ...
}

Funciones adicionales de la IU

Ventana emergente

Una ventana emergente es un archivo HTML que se muestra en una ventana especial cuando el usuario hace clic en el ícono de la barra de herramientas. Una ventana emergente funciona de manera muy similar a una página web. Puede contener vínculos a hojas de estilo y etiquetas de secuencia de comandos, pero no permite JavaScript intercalado.

La ventana emergente de ejemplo Drink Water Event muestra las opciones de temporizador disponibles. Los usuarios configuran una alarma haciendo clic en uno de los botones proporcionados.

<html>
  <head>
    <title>Water Popup</title>
  </head>
  <body>
      <img src='./stay_hydrated.png' id='hydrateImage'>
      <button id='sampleSecond' value='0.1'>Sample Second</button>
      <button id='15min' value='15'>15 Minutes</button>
      <button id='30min' value='30'>30 Minutes</button>
      <button id='cancelAlarm'>Cancel Alarm</button>
    <script src="popup.js"></script>
  </body>
</html>

La ventana emergente se puede registrar en el manifiesto, en la acción del navegador o en la acción de la página.

{
  "name": "Drink Water Event",
  ...
  "browser_action": {
    "default_popup": "popup.html"
  }
  ...
}

Las ventanas emergentes también se pueden configurar de forma dinámica llamando a browserAction.setPopup o pageAction.setPopup.

chrome.storage.local.get('signed_in', function(data) {
  if (data.signed_in) {
    chrome.browserAction.setPopup({popup: 'popup.html'});
  } else {
    chrome.browserAction.setPopup({popup: 'popup_sign_in.html'});
  }
});

Información sobre la herramienta

Usa una información sobre la herramienta para dar instrucciones o descripciones breves a los usuarios cuando colocan el cursor sobre el ícono del navegador.

Las informaciones sobre la herramienta se registran en el "default_title" campo browser_action o page_action en el manifiesto.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "Press Ctrl(Win)/Command(Mac)+Shift+Right/Left to flip tabs"
  }
...
}

Las informaciones sobre la herramienta también se pueden configurar o actualizar llamando a browserAction.setTitle y pageAction.setTitle.

chrome.browserAction.onClicked.addListener(function(tab) {
  chrome.browserAction.setTitle({tabId: tab.id, title: "You are on tab:" + tab.id});
});

Las cadenas de configuración regional especializadas se implementan con la internacionalización. Crea directorios para alojar mensajes específicos del idioma en una carpeta llamada _locales, de la siguiente manera:

• _locales/en/messages.json
• _locales/es/messages.json

Formatea los mensajes dentro de messages.json de cada idioma.

{
  "__MSG_tooltip__": {
      "message": "Hello!",
      "description": "Tooltip Greeting."
  }
}

{
  "__MSG_tooltip__": {
      "message": "Hola!",
      "description": "Tooltip Greeting."
  }
}

Incluye el nombre del mensaje en el campo de información sobre la herramienta en lugar del mensaje para habilitar la localización.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "__MSG_tooltip__"
  }
...
}

Cuadro multifunción

Los usuarios pueden invocar la funcionalidad de la extensión a través del cuadro multifunción. Incluye el campo "omnibox" en el manifiesto y designa una palabra clave. La extensión de ejemplo Omnibox New Tab Search usa "nt" como palabra clave.

{
  "name": "Omnibox New Tab Search",\
  ...
  "omnibox": { "keyword" : "nt" },
  "default_icon": {
    "16": "newtab_search16.png",
    "32": "newtab_search32.png"
  }
  ...
}

Cuando el usuario escribe "nt" en el cuadro multifunción, se activa la extensión. Para indicarle esto al usuario, se muestra en escala de grises el ícono de 16x16 proporcionado y se incluye en el cuadro multifunción junto al nombre de la extensión.

La extensión escucha el omnibox.onInputEntered evento. Después de que se activa, la extensión abre una pestaña nueva que contiene una búsqueda de Google para la entrada del usuario.

chrome.omnibox.onInputEntered.addListener(function(text) {
  // Encode user input for special characters , / ? : @ & = + $ #
  var newURL = 'https://www.google.com/search?q=' + encodeURIComponent(text);
  chrome.tabs.create({ url: newURL });
});

Menú contextual

Para agregar nuevas opciones de menú contextual, otorga el permiso "contextMenus" en el manifiesto.

{
  "name": "Global Google Search",
  ...
  "permissions": [
    "contextMenus",
    "storage"
  ],
  "icons": {
    "16": "globalGoogle16.png",
    "48": "globalGoogle48.png",
    "128": "globalGoogle128.png"
  }
  ...
}

El ícono de 16x16 se muestra junto a la nueva entrada de menú.

Para crear un menú contextual, llama a contextMenus.create en la secuencia de comandos en segundo plano. Esto se debe hacer en el runtime.onInstalled evento de escucha.

chrome.runtime.onInstalled.addListener(function() {
  for (let key of Object.keys(kLocales)) {
    chrome.contextMenus.create({
      id: key,
      title: kLocales[key],
      type: 'normal',
      contexts: ['selection'],
    });
  }
});

const kLocales = {
  'com.au': 'Australia',
  'com.br': 'Brazil',
  'ca': 'Canada',
  'cn': 'China',
  'fr': 'France',
  'it': 'Italy',
  'co.in': 'India',
  'co.jp': 'Japan',
  'com.ms': 'Mexico',
  'ru': 'Russia',
  'co.za': 'South Africa',
  'co.uk': 'United Kingdom'
};

En el ejemplo de menú contextual de Búsqueda de Google global, se crean varias opciones de la lista en locales.js . Cuando una extensión contiene más de un menú contextual, Google Chrome los contrae automáticamente en un solo menú superior.

Comandos

Las extensiones pueden definir comandos específicos y vincularlos a una combinación de teclas. Registra uno o más comandos en el manifiesto en el "commands" campo.

{
  "name": "Tab Flipper",
  ...
  "commands": {
    "flip-tabs-forward": {
      "suggested_key": {
        "default": "Ctrl+Shift+Right",
        "mac": "Command+Shift+Right"
      },
      "description": "Flip tabs forward"
    },
    "flip-tabs-backwards": {
      "suggested_key": {
        "default": "Ctrl+Shift+Left",
        "mac": "Command+Shift+Left"
      },
      "description": "Flip tabs backwards"
    }
  }
  ...
}

Los comandos se pueden usar para proporcionar combinaciones de teclas nuevas o alternativas del navegador. La extensión de ejemplo Tab Flipper escucha el evento commands.onCommand en la secuencia de comandos en segundo plano y define la funcionalidad para cada combinación registrada.

chrome.commands.onCommand.addListener(function(command) {
  chrome.tabs.query({currentWindow: true}, function(tabs) {
    // Sort tabs according to their index in the window.
    tabs.sort((a, b) => { return a.index < b.index; });
    let activeIndex = tabs.findIndex((tab) => { return tab.active; });
    let lastTab = tabs.length - 1;
    let newIndex = -1;
    if (command === 'flip-tabs-forward')
      newIndex = activeIndex === 0 ? lastTab : activeIndex - 1;
    else  // 'flip-tabs-backwards'
      newIndex = activeIndex === lastTab ? 0 : activeIndex + 1;
    chrome.tabs.update(tabs[newIndex].id, {active: true, highlighted: true});
  });
});

Los comandos también pueden crear una vinculación de teclas que funcione especialmente con su extensión. En el ejemplo de Hello Extensions, se proporciona un comando para abrir la ventana emergente.

{
  "name": "Hello Extensions",
  "description" : "Base Level Extension",
  "version": "1.0",
  "browser_action": {
    "default_popup": "hello.html",
    "default_icon": "hello_extensions.png"
  },
  "manifest_version": 2,
  "commands": {
    "_execute_browser_action": {
      "suggested_key": {
        "default": "Ctrl+Shift+F",
        "mac": "MacCtrl+Shift+F"
      },
      "description": "Opens hello.html"
    }
  }
}

Debido a que la extensión define un browser_action, puede especificar "execute_browser_action" en los comandos para abrir el archivo emergente sin incluir una secuencia de comandos en segundo plano. Si usas page_action, se puede reemplazar por "execute_page_action". Se pueden usar comandos del navegador y de la extensión en la misma extensión.

Anula páginas

Una extensión puede anular y reemplazar la página web Historial, Nueva pestaña o Marcadores por un archivo HTML personalizado. Al igual que una ventana emergente, puede incluir lógica y estilo especializados, pero no permite JavaScript intercalado. Una sola extensión se limita a anular solo una de las tres páginas posibles.

Registra una página de anulación en el manifiesto en el campo "chrome_url_overrides".

{
  "name": "Awesome Override Extension",
  ...

  "chrome_url_overrides" : {
    "newtab": "override_page.html"
  },
  ...
}

El campo "newtab" debe reemplazarse por "bookmarks" o "history" cuando se anulan esas páginas.

<html>
  <head>
  <title>New Tab</title>
  </head>
  <body>
    <h1>Hello World</h1>
  <script src="logic.js"></script>
  </body>
</html>