chrome.sidePanel

Descripción

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

Permisos

sidePanel

Para usar la API del panel lateral, 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 y versiones posteriores

Conceptos y uso

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

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

Estas son algunas de sus funciones:

  • El panel lateral permanece abierto cuando navegas entre pestañas (si está configurado para hacerlo).
  • Puede estar disponible solo en sitios web específicos.
  • Como página de 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 del panel lateral. Consulta Muestras de extensiones para ver ejemplos completos de extensiones.

Muestra el mismo panel lateral en todos los sitios

Inicialmente, el panel lateral se puede configurar desde la propiedad "default_path" en la clave "side_panel" del manifiesto para que se muestre el mismo panel 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 de la pestaña. Verifica 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
    });
  }
});

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

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

Para obtener un ejemplo completo, consulta el ejemplo del panel lateral específico de una pestaña.

Haz clic en el ícono de la barra de herramientas para abrir el panel lateral

Los desarrolladores pueden permitir que los usuarios abran el panel lateral cuando hacen clic en el ícono de la barra de herramientas de acciones 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 de manera programática el panel lateral en la interacción del usuario

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

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 uses sidePanel.open(), deberás elegir el contexto en el que se debe abrir. Usa windowId para abrir un panel lateral global. También puedes configurar tabId para abrir 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 });
  }
});

Cambiar a un panel diferente

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.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

Consulta Varios paneles laterales para ver una muestra completa.

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.

Cómo abrir el panel lateral

Navega al menú del panel lateral
Los usuarios pueden encontrar los paneles laterales disponibles en el menú del panel lateral. Luego, puede elegir una extensión en el menú desplegable.
Menú desplegable del panel lateral
IU del panel lateral del navegador Chrome.
Abre con un gesto del usuario

Puedes abrir el panel lateral a través de las interacciones del usuario con sidePanel.open() y sidePanel.setPanelBehavior(), por ejemplo:

Ejemplos

Para ver más demostraciones de extensiones de la API del panel lateral, 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 correspondiente. De lo contrario, muestra las opciones predeterminadas del panel lateral (que se usan para todas las pestañas que no tienen parámetros de configuración específicos).

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 para esa 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 de pestaña abierta actualmente. Esta acción anulará cualquier panel lateral que esté activo actualmente (global o específico de una 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. Esta acción anulará cualquier panel lateral global que esté activo 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, se mostrará la entrada de la extensión en el panel lateral. La configuración predeterminada es "false".

PanelOptions

Propiedades

  • habilitado

    booleano opcional

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

  • ruta de acceso

    cadena 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 omite, estas opciones establecen el comportamiento predeterminado (se usa para cualquier pestaña que no tiene 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 al panel para el tabId predeterminado.

SidePanel

Propiedades

  • default_path

    cadena

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

Métodos

getOptions()

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

Devuelve la configuración activa del panel.

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

Devuelve

  • Promise<PanelOptions>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa 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

Devuelve

  • Promise<PanelBehavior>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa 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 la acción de un usuario.

Parámetros

  • Opciones

    OpenOptions

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

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa 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

    Las opciones de configuración que se aplicarán al panel.

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa 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

  • el comportamiento de los consumidores

    PanelBehavior

    El comportamiento nuevo que se establecerá.

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

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