chrome.sidePanel

Descripción

Usa la API de chrome.sidePanel para alojar contenido en el panel lateral del navegador junto con el contenido principal de una página web.

Permisos

sidePanel

Para usar la API de Side Panel, agrega el permiso "sidePanel" en el archivo de manifiesto de la extensión:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

Disponibilidad

Chrome 114 y versiones posteriores MV3+ .

Conceptos y uso

La API de Side Panel permite que las extensiones muestren su propia IU en el panel lateral, lo que permite experiencias persistentes que complementan la experiencia de navegación del usuario.

Menú desplegable del panel lateral
IU del panel lateral del navegador Chrome.

Estas son algunas de las funciones:

  • El panel lateral permanecerá abierto cuando navegues entre pestañas (si está configurado para hacerlo).
  • Puede estar disponible solo en sitios web específicos.
  • Como página de la extensión, los paneles laterales tienen acceso a todas las APIs de Chrome.
  • Dentro de la configuración de Chrome, los usuarios pueden especificar en qué lado se debe mostrar el panel.

Casos de uso

En las siguientes secciones, se muestran algunos casos de uso comunes para la API de Side Panel. Consulta los ejemplos de extensiones para ver ejemplos completos de extensiones.

Mostrar el mismo panel lateral en todos los sitios

El panel lateral se puede configurar inicialmente desde la propiedad "default_path" en la clave "side_panel" del manifiesto para mostrar el mismo panel lateral en todos los sitios. Esto debería apuntar a una ruta de acceso relativa dentro del directorio de la extensión.

manifest.json:

{
  "name": "My side panel extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  }
  ...
}

sidepanel.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Sidepanel</title>
  </head>
  <body>
    <h1>All sites sidepanel extension</h1>
    <p>This side panel is enabled on all sites</p>
  </body>
</html>

Cómo habilitar un panel lateral en un sitio específico

Una extensión puede usar sidepanel.setOptions() para habilitar un panel lateral en una pestaña específica. En este ejemplo, se usa chrome.tabs.onUpdated() para escuchar las actualizaciones que se realizan en la pestaña. Comprueba si la URL es www.google.com y habilita el panel lateral. De lo contrario, la inhabilita.

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the side panel on google.com
  if (url.origin === GOOGLE_ORIGIN) {
    await chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await chrome.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

Cuando un usuario cambia temporalmente a una pestaña en la que el panel lateral no está habilitado, el panel lateral se ocultará. Se volverá a mostrar automáticamente cuando el usuario cambie a una pestaña en la que estaba abierta anteriormente.

Cuando el usuario navegue a un sitio en el que el panel lateral no está habilitado, este se cerrará y la extensión no se mostrará en el menú desplegable del panel lateral.

Para ver un ejemplo completo, consulta la muestra del panel lateral específico de la pestaña.

Abre el panel lateral haciendo clic en el ícono de la barra de herramientas

Los desarrolladores pueden permitir que los usuarios abran el panel lateral cuando hagan clic en el ícono de acciones de la barra de herramientas con sidePanel.setPanelBehavior(). Primero, declara la clave "action" en el manifiesto:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "action": {
    "default_title": "Click to open panel"
  },
  ...
}

Ahora, agrega este código al ejemplo anterior:

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

// Allows users to open the side panel by clicking on the action toolbar icon
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

Abre el panel lateral de manera programática cuando el usuario interactúa

Chrome 116 presenta sidePanel.open(). Permite que las extensiones abran el panel lateral mediante un gesto del usuario de una extensión, como hacer clic en el ícono de acción. O bien cuando el usuario interactúa con la página de una extensión o una secuencia de comandos de contenido, como hacer clic en un botón. Para ver una demostración completa, consulta la extensión de muestra Abrir panel lateral.

En el siguiente código, se muestra cómo abrir un panel lateral global en la ventana actual cuando el usuario hace clic en un menú contextual. Cuando usas sidePanel.open(), debes elegir el contexto en el que se debe abrir. Usa windowId para abrir un panel lateral global. Como alternativa, configura tabId para que abra el panel lateral solo en una pestaña específica.

service-worker.js:

chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open side panel',
    contexts: ['all']
  });
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // This will open the panel in all the pages on the current window.
    chrome.sidePanel.open({ windowId: tab.windowId });
  }
});

Cómo cambiar a otro panel

Las extensiones pueden usar sidepanel.getOptions() para recuperar el panel lateral actual. En el siguiente ejemplo, se configura un panel lateral de bienvenida en runtime.onInstalled(). Luego, cuando el usuario navegue a una pestaña diferente, la reemplazará por el panel lateral principal.

service-worker.js:

const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';

chrome.runtime.onInstalled.addListener(() => {
  chrome.sidePanel.setOptions({ path: welcomePage });
  chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

chrome.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

Consulta el ejemplo de Varios paneles laterales para ver el código completo.

Experiencia del usuario del panel lateral

Los usuarios verán primero los paneles laterales integrados de Chrome. Cada panel lateral muestra el ícono de la extensión en el menú del panel lateral. Si no se incluyen íconos, se mostrará un ícono de marcador de posición con la primera letra del nombre de la extensión.

Abrir el panel lateral

Para permitir que los usuarios abran el panel lateral, usa un ícono de acción combinado con sidePanel.setPanelBehavior(). También puedes realizar una llamada a sidePanel.open() después de una interacción del usuario; por ejemplo:

Fijar el panel lateral

Ícono de fijar en la IU del panel lateral.
Ícono de fijar en la IU del panel lateral.

La barra de herramientas del panel lateral muestra un ícono de marcador cuando el panel lateral está abierto. Cuando haces clic en él, se fija el ícono de acción de tu extensión. Hacer clic en el ícono de acción una vez fijado, realizará la acción predeterminada para el ícono de acción y solo abre el panel lateral si se configuró explícitamente.

Ejemplos

Para ver más demostraciones de las extensiones de la API de Side Panel, explora cualquiera de las siguientes extensiones:

Tipos

GetPanelOptions

Propiedades

  • tabId

    número opcional

    Si se especifica, se mostrarán las opciones del panel lateral para la pestaña dada. De lo contrario, muestra las opciones predeterminadas del panel lateral (que se usan para cualquier pestaña que no tenga una configuración específica).

OpenOptions

Chrome 116 y versiones posteriores

Propiedades

  • tabId

    número opcional

    La pestaña en la que se abre el panel lateral. Si la pestaña correspondiente tiene un panel lateral específico de una pestaña, el panel solo se abrirá para esa pestaña. Si no hay un panel específico de una pestaña, el panel global se abrirá en la pestaña especificada y en cualquier otra pestaña que no tenga un panel específico abierto actualmente. Esta acción anulará cualquier panel lateral que esté activo actualmente (global o específico de pestaña) en la pestaña correspondiente. Se debe proporcionar, al menos, uno de estos valores o windowId.

  • windowId

    número opcional

    La ventana en la que se abre el panel lateral. Esto solo es aplicable si la extensión tiene un panel lateral global (no específico de una pestaña) o si también se especifica tabId. Esto anulará cualquier panel lateral global que esté activo en ese momento y que el usuario haya abierto en la ventana determinada. Se debe proporcionar, al menos, uno de estos valores o tabId.

PanelBehavior

Propiedades

  • openPanelOnActionClick

    booleano opcional

    Si se hace clic en el ícono de la extensión, la entrada de la extensión se mostrará en el panel lateral. La configuración predeterminada es "false".

PanelOptions

Propiedades

  • habilitado

    booleano opcional

    Si se debe habilitar el panel lateral Esto es opcional. El valor predeterminado es verdadero.

  • ruta de acceso

    string opcional

    La ruta de acceso al archivo HTML del panel lateral que se usará. Debe ser un recurso local dentro del paquete de la extensión.

  • tabId

    número opcional

    Si se especifica, las opciones del panel lateral solo se aplicarán a la pestaña con este ID. Si se omiten, estas opciones establecen el comportamiento predeterminado (se usa para cualquier pestaña que no tenga una configuración específica). Nota: Si se configura la misma ruta de acceso para este tabId y el tabId predeterminado, el panel para este tabId será una instancia diferente del panel para el tabId predeterminado.

SidePanel

Propiedades

  • default_path

    string

    Ruta especificada por el desarrollador para la visualización del panel lateral.

Métodos

getOptions()

Promesa 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

Muestra la configuración del panel activo.

Parámetros

  • opciones

    GetPanelOptions

    Especifica el contexto para el que se mostrará la configuración.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (options: PanelOptions) => void

Muestra

  • Promise&lt;PanelOptions&gt;

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getPanelBehavior()

Promesa 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

Muestra el comportamiento actual del panel lateral de la extensión.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (behavior: PanelBehavior) => void

Muestra

  • Promise&lt;PanelBehavior&gt;

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

open()

Promesa Chrome 116 y versiones posteriores .
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

Abre el panel lateral de la extensión. Solo se puede llamar en respuesta a una acción del usuario.

Parámetros

  • opciones

    OpenOptions

    Especifica el contexto en el que se abrirá el panel lateral.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

setOptions()

Promesa 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

Configura el panel lateral.

Parámetros

  • opciones

    PanelOptions

    Son las opciones de configuración que se aplican al panel.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

setPanelBehavior()

Promesa 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

Configura el comportamiento del panel lateral de la extensión. Esta es una operación de inserción y actualización.

Parámetros

  • comportamiento

    PanelBehavior

    El nuevo comportamiento que se establecerá.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.