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
sidePanelPara usar la API de Side Panel, agrega el permiso "sidePanel" en el archivo manifest de la extensión:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
Disponibilidad
Conceptos y uso
La API de Side Panel 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 las funciones:
- El panel lateral permanece abierto cuando se navega entre pestañas (si se configura para que lo haga).
- 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.
- En 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 de la API de Side Panel. Consulta Muestras 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 cada sitio. Debe 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 browser.tabs.onUpdated() para escuchar las actualizaciones que se realicen en la pestaña. Verifica si la URL es www.google.com y habilita el panel lateral. De lo contrario, lo inhabilita.
service-worker.js:
const GOOGLE_ORIGIN = 'https://www.google.com';
browser.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 browser.sidePanel.setOptions({
tabId,
path: 'sidepanel.html',
enabled: true
});
} else {
// Disables the side panel on all other sites
await browser.sidePanel.setOptions({
tabId,
enabled: false
});
}
});
Cuando un usuario cambie temporalmente a una pestaña en la que el panel lateral no esté habilitado, este se ocultará. Volverá a aparecer automáticamente cuando el usuario cambie a una pestaña en la que estaba abierto.
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 de 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 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
browser.sidePanel
.setPanelBehavior({ openPanelOnActionClick: true })
.catch((error) => console.error(error));
...
Abre el panel lateral de forma programática cuando el usuario interactúa con la extensión
Chrome 116 presenta sidePanel.open(). Permite que las extensiones abran el panel lateral a través de un gesto del usuario de la extensión, como hacer clic en el ícono de acción. O una interacción del usuario en una página de extensión o una secuencia de comandos de contenido, como hacer clic en un botón. Para obtener una demostración completa, consulta la extensión de ejemplo 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 uses 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 abrir el panel lateral solo en una pestaña específica.
service-worker.js:
browser.runtime.onInstalled.addListener(() => {
browser.contextMenus.create({
id: 'openSidePanel',
title: 'Open side panel',
contexts: ['all']
});
});
browser.contextMenus.onClicked.addListener((info, tab) => {
if (info.menuItemId === 'openSidePanel') {
// This will open the panel in all the pages on the current window.
browser.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 navega a una pestaña diferente, se reemplaza por el panel lateral principal.
service-worker.js:
const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';
browser.runtime.onInstalled.addListener(() => {
browser.sidePanel.setOptions({ path: welcomePage });
browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});
browser.tabs.onActivated.addListener(async ({ tabId }) => {
const { path } = await browser.sidePanel.getOptions({ tabId });
if (path === welcomePage) {
browser.sidePanel.setOptions({ path: mainPage });
}
});
Consulta el ejemplo de varios paneles laterales para ver el código completo.
Experiencia del usuario en el 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 en combinación con sidePanel.setPanelBehavior(). Como alternativa, realiza una llamada a sidePanel.open() después de una interacción del usuario, como las siguientes:
- 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 una secuencia de comandos de contenido.
Fijar el panel lateral
La barra de herramientas del panel lateral muestra un ícono de fijar cuando el panel lateral está abierto. Si haces clic en el ícono, se fijará el ícono de acción de la 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 se configuró de forma explícita.
Ejemplos
Para ver más demostraciones de extensiones de la API de Side Panel, explora cualquiera de las siguientes extensiones:
- Panel lateral del diccionario.
- Panel lateral global.
- Varios paneles laterales.
- Abrir el panel lateral
- Panel lateral específico del sitio.
Tipos
CloseOptions
Propiedades
-
tabId
number opcional
Es la pestaña en la que se cerrará el panel lateral. Si hay un panel lateral específico de la pestaña abierto en la pestaña especificada, se cerrará para esa pestaña. Si solo está abierto el panel lateral global, la promesa que devuelve la llamada a
close()se rechazará con un error. Este comportamiento se cambió en Chrome 145, y las versiones anteriores volvieron a cerrar el panel global. Se debe proporcionar, al menos, uno de estos valores owindowId. -
windowId
number opcional
Es la ventana en la que se cerrará el panel lateral. Si hay un panel lateral global abierto en la ventana especificada, se cerrará para todas las pestañas de esa ventana en las que no haya un panel específico de la pestaña activo. Se debe proporcionar, al menos, uno de estos valores o
tabId.
GetPanelOptions
Propiedades
-
tabId
number opcional
Si se especifica, se devolverán las opciones del panel lateral para la pestaña determinada. De lo contrario, devuelve las opciones predeterminadas del panel lateral (que se usan para cualquier pestaña que no tenga una configuración específica).
OpenOptions
Propiedades
-
tabId
number opcional
Es la pestaña en la que se abrirá el panel lateral. Si la pestaña correspondiente tiene un panel lateral específico, el panel solo se abrirá para esa pestaña. Si no hay un panel específico de la 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 la pestaña abierto en ese momento. Esto anulará cualquier panel lateral activo (global o específico de la pestaña) en la pestaña correspondiente. Se debe proporcionar, al menos, uno de estos valores o
windowId. -
windowId
number opcional
Es la ventana en la que se abrirá el panel lateral. Esto solo se aplica 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 activo que el usuario tenga abierto en la ventana determinada. Se debe proporcionar, al menos, uno de estos valores otabId.
PanelBehavior
Propiedades
-
openPanelOnActionClick
booleano opcional
Indica si, cuando se hace clic en el ícono de la extensión, se activa o desactiva la visualización de la entrada de la extensión en el panel lateral. La configuración predeterminada es "false".
PanelClosedInfo
Propiedades
-
ruta de acceso
string
Es la ruta de acceso del recurso local dentro del paquete de extensión cuyo contenido se muestra en el panel.
-
tabId
number opcional
Es el ID opcional de la pestaña en la que se cerró el panel lateral. Esto solo se proporciona cuando el panel es específico de la pestaña.
-
windowId
número
Es el ID de la ventana en la que se cerró el panel lateral. Esta opción está disponible para los paneles globales y específicos de pestañas.
PanelLayout
Propiedades
-
equipo
PanelOpenedInfo
Propiedades
-
ruta de acceso
string
Es la ruta de acceso del recurso local dentro del paquete de extensión cuyo contenido se muestra en el panel.
-
tabId
number opcional
Es el ID opcional de la pestaña en la que se abre el panel lateral. Esto solo se proporciona cuando el panel es específico de la pestaña.
-
windowId
número
Es el ID de la ventana en la que se abre el panel lateral. Esta opción está disponible para los paneles globales y específicos de pestañas.
PanelOptions
Propiedades
-
habilitado
booleano opcional
Indica si se debe habilitar el panel lateral. Esto es opcional. El valor predeterminado es verdadero.
-
ruta de acceso
string opcional
Es la ruta de acceso al archivo HTML del panel lateral que se usará. Debe ser un recurso local dentro del paquete de extensión.
-
tabId
number 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 (que se usa para cualquier pestaña que no tenga parámetros de configuración específicos). Nota: Si se establece la misma ruta de acceso para este tabId y el tabId predeterminado, el panel de este tabId será una instancia diferente de la del panel del tabId predeterminado.
Side
Define la alineación posible para el panel lateral en la IU del navegador.
Enum
"left"
"right"
SidePanel
Propiedades
-
default_path
string
Ruta de acceso especificada por el desarrollador para la visualización del panel lateral.
Métodos
close()
browser.sidePanel.close(
options: CloseOptions,
): Promise<void>
Cierra el panel lateral de la extensión. Esta acción no tiene efecto si el panel ya está cerrado.
Parámetros
-
opciones
Especifica el contexto en el que se debe cerrar el panel lateral.
Muestra
-
Promise<void>
Devuelve una promesa que se resuelve cuando se cierra el panel lateral.
getLayout()
browser.sidePanel.getLayout(): Promise<PanelLayout>
Devuelve el diseño actual del panel lateral.
Muestra
-
Promise<PanelLayout>
Devuelve una promesa que se resuelve con un
PanelLayout.
getOptions()
browser.sidePanel.getOptions(
options: GetPanelOptions,
): Promise<PanelOptions>
Devuelve la configuración del panel activo.
Parámetros
-
opciones
Especifica el contexto para el que se devolverá la configuración.
Muestra
-
Promise<PanelOptions>
Devuelve una promesa que se resuelve con la configuración del panel activo.
getPanelBehavior()
browser.sidePanel.getPanelBehavior(): Promise<PanelBehavior>
Devuelve el comportamiento actual del panel lateral de la extensión.
Muestra
-
Promise<PanelBehavior>
Devuelve una promesa que se resuelve con el comportamiento del panel lateral de la extensión.
open()
browser.sidePanel.open(
options: OpenOptions,
): Promise<void>
Abre el panel lateral de la extensión. Solo se puede llamar en respuesta a una acción del usuario.
Parámetros
-
opciones
Especifica el contexto en el que se abrirá el panel lateral.
Muestra
-
Promise<void>
Devuelve una promesa que se resuelve cuando se abre el panel lateral.
setOptions()
browser.sidePanel.setOptions(
options: PanelOptions,
): Promise<void>
Configura el panel lateral.
Parámetros
-
opciones
Son las opciones de configuración que se aplicarán al panel.
Muestra
-
Promise<void>
Devuelve una promesa que se resuelve cuando se configuran las opciones.
setPanelBehavior()
browser.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
): Promise<void>
Configura el comportamiento del panel lateral de la extensión. Esta es una operación de actualización o inserción.
Parámetros
-
comportamiento
Es el nuevo comportamiento que se establecerá.
Muestra
-
Promise<void>
Devuelve una promesa que se resuelve cuando se establece el comportamiento nuevo.
Eventos
onClosed
browser.sidePanel.onClosed.addListener(
callback: function,
)
Se activa cuando se cierra el panel lateral de la extensión.
Parámetros
-
callback
función
El parámetro
callbackse ve de la siguiente manera:(info: PanelClosedInfo) => void
-
información
-
onOpened
browser.sidePanel.onOpened.addListener(
callback: function,
)
Se activa cuando se abre el panel lateral de la extensión.
Parámetros
-
callback
función
El parámetro
callbackse ve de la siguiente manera:(info: PanelOpenedInfo) => void
-
información
-