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
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.
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.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.
Cómo abrir el panel lateral
Para permitir que los usuarios abran el panel lateral, usa un ícono de acción junto con sidePanel.setPanelBehavior()
. También puedes realizar una llamada a sidePanel.open()
después de la interacción del usuario; por ejemplo:
- Un clic de acción
- Una combinación de teclas
- Un menú contextual
- Un gesto del usuario en una página de extensión o secuencia de comandos de contenido.
Fija el panel lateral
La barra de herramientas del panel lateral muestra un ícono para fijar cuando tu panel lateral está abierto. Cuando haces clic en el ícono, se fija el ícono de acción de tu extensión. Si haces clic en el ícono de acción una vez fijado, se realizará la acción predeterminada para tu ícono de acción y solo se abrirá el panel lateral si esto se configuró de forma explícita.
Ejemplos
Para ver más demostraciones de extensiones de la API del panel lateral, explora cualquiera de las siguientes extensiones:
- Panel lateral del diccionario:
- Panel lateral global.
- Varios paneles laterales.
- Abre el panel lateral.
- Panel lateral específico del sitio.
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
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 otabId
.
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()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
Devuelve la configuración activa del panel.
Parámetros
-
Opciones
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
-
Opciones
-
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()
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
-
el comportamiento de los consumidores
-
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()
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
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()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
Configura el panel lateral.
Parámetros
-
Opciones
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()
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
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.