BrowserWindow
Crea y controla las ventanas del navegador.
Process: Main
Este módulo no puede ser usado hasta que el evento ready
del módulo app
es emitido.
/// In the main process.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
// Load a remote URL
win.loadURL('https://github.com')
// Or load a local HTML file
win.loadFile('index.html')
Window customization
The BrowserWindow
class exposes various ways to modify the look and behavior of your app's windows. For more details, see the Window Customization tutorial.
Mostrar la ventana con gracia
Cuando se carga una página directamente en la ventana, los usuarios pueden ver la página de forma incremental, lo cual no es una buena experiencia para aplicación nativa. Para hacer que la ventana muestre sin un flash visual, hay dos soluciones para diferente situaciones.
Usando el evento ready-to-show
Mientras se carga la página, se emitirá el evento ready-to-show
cuando el proceso de renderizado haya procesado la página por primera vez si aún no se ha mostrado la ventana. Si se muestra la ventana despues de este evento, no tendrá fogonazos:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ show: false })
win.once('ready-to-show', () => {
win.show()
})
Este evento generalmente se emite después del evento did-finish-load
, pero para páginas con muchos recursos remotos, puede ser emitido antes del evento did-finish-load
.
Por favor tenga en cuanta que usando este evento implica que el renderer será considerado "visible" y se pintara incluso si show
es falso. Este evento nunca se disparará si usa paintWhenInitiallyHidden: false
Estableciendo la propiedad backgroundColor
Para una aplicación compleja, el evento ready-to-show
puede emitirse muy tarde, haciendo que la aplicación parezca lenta. En este caso, se recomienda mostrar la ventana inmediatamente, y usar un color de fondo backgroundColor
parecido al color de fondo de la aplicación:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ backgroundColor: '#2e2c29' })
win.loadURL('https://github.com')
Note that even for apps that use ready-to-show
event, it is still recommended to set backgroundColor
to make the app feel more native.
Some examples of valid backgroundColor
values include:
const win = new BrowserWindow()
win.setBackgroundColor('hsl(230, 100%, 50%)')
win.setBackgroundColor('rgb(255, 145, 145)')
win.setBackgroundColor('#ff00a3')
win.setBackgroundColor('blueviolet')
For more information about these color types see valid options in win.setBackgroundColor.
Ventana principal y ventana secundaria
Al usar la opción parent
, se pueden crean ventanas secundarias:
const { BrowserWindow } = require('electron')
const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top })
child.show()
top.show()
La ventana child
se mostrará siempre por encima de la ventana top
.
Ventanas modales
A modal window is a child window that disables parent window. Para crear una ventana modal, tienes que configurar las opciones parent
y modal
:
const { BrowserWindow } = require('electron')
const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top, modal: true, show: false })
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
child.show()
})
La visibilidad de la página
La Page Visibility API funciona de la siguiente manera:
- En todas las plataformas, el estado de visibilidad identifica si la ventana está oculta/minimizada o si no lo está.
- Además, en macOS, el estado de visibilidad también indica el estado de oclusión de la ventana. Si la ventana esta tapada, es decir, completamente cubierta por otra ventana, el estado de visibilidad será
hidden
. En otras plataformas, el estado de visibilidad seráhidden
solo si la ventana esta minimizada o explícitamente oculta conwin.hide()
. - Si se crea un
BrowserWindow
conshow: false
, el estado de visibilidad inicial serávisible
a pesar de que la ventana esté oculta realmente. - Si
backgroundThrottling
está deshabilitado, el estado de visibilidad permanecerávisible
incluso si la ventana está minimizada, tapada o oculta.
Se recomienda detener operaciones costosas cuando el estado de visibilidad está hidden
con el fin de minimizar el consumo de energía.
Notas según la plataforma
- En macOS las ventanas modales se mostrarán como hojas adjuntas a la ventana principal.
- En macOS las ventanas secundarias mantendrán la posición relativa a la ventana principal cuando ésta se mueve, mientras que en Windows y Linux las ventanas secundarias no se moverán.
- En Linux el tipo de ventanas modales se cambiará a
dialog
. - En Linux, muchos entornos de escritorio no admiten ocultar una ventana modal.
Clase: BrowserWindow extiende BaseWindow
Crea y controla las ventanas del navegador.
Process: Main
BrowserWindow
es un EventEmitter.
Crea una nueva BrowserWindow
con propiedades nativas como las establecidas por las options
.
new BrowserWindow([options])
Eventos de Instancia
Los objetos creados con new BrowserWindow
emiten los siguientes eventos:
Nota: Algunos eventos sólo están disponibles en sistemas operativos específicos y se etiquetan como tal.
Evento: 'page-title-updated'
Devuelve:
event
title
stringexplicitSet
boolen
Aparece cuando el documento cambia el título. Llamar event.preventDefault()
evitará que el título de la ventana nativa cambie. explicitSet
es falso cuando el título se sintetiza a partir de la URL del archivo.
Evento: "close"
Devuelve:
event
Aparece cuando la ventana se va a cerrar. Se emite antes de el evento del DOM beforeunload
y unload
. Llamar a event.preventDefault()
cancelará el cierre.
Generalmente se desea utilizar el controlador beforeunload
para decidir si la ventana debería ser cerrada, el cual también será llamado cuando la ventada se vuelva a cargar. En Electron, devolver cualquier valor que no sea undefined
cancelará el cierre. Por ejemplo:
window.onbeforeunload = (e) => {
console.log('I do not want to be closed')
// Unlike usual browsers that a message box will be prompted to users, returning
// a non-void value will silently cancel the close.
// It is recommended to use the dialog API to let the user confirm closing the
// application.
e.returnValue = false
}
Nota: Hay una diferencia sutil entre el comportamiento de window.onbeforeunload = handler
y window.addEventListener('beforeunload', handler)
. Se recomienda siempre establecer el event.returnValue
explícitamente, en lugar de devolver sólo un valor, ya que el primero funciona más consistentemente dentro de Electron.
Evento: "closed"
Emitted when the window is closed. Después de haber recibido este evento, debe eliminar la referencia a la ventana y evitar volverla a usar.
Evento: "session-end" Windows
Aparece cuando la sesión de la ventana va a terminarse debido a un cierre forzoso o el reinicio de la máquina o el cierre de la sesión.
Evento: "unresponsive"
Aparece cuando la página web deja de responder.
Evento: "responsive"
Aparece cuando la página web que no responde vuelve a responder.
Evento: "blur"
Aparece cuando la ventana pierde el enfoque.
Evento: "focus"
Aparece cuando la ventana recupera el enfoque.
Evento: "show"
Aparece cuando se muestra la ventana.
Evento: "hide"
Aparece cuando se oculta la ventana.
Evento: "ready-to-show"
Aparece cuando la página web ha sido renderizada (mientras no está siendo mostrada) y la ventana puede mostrarse sin un visual flash.
Por favor tenga en cuanta que usando este evento implica que el renderer será considerado "visible" y se pintara incluso si show
es falso. Este evento nunca se disparará si usa paintWhenInitiallyHidden: false
Evento: "maximize"
Aparece cuando se maximiza la ventana.
Evento: "unmaximize"
Aparece cuando la ventana sale de un estado maximizado.
Evento: "minimize"
Aparece cuando se minimiza la ventana.
Evento: "restore"
Aparece cuando se restaura la ventana de un estado minimizado.
Event: 'will-resize' macOS Windows
Devuelve:
event
newBounds
Rectangle - Tamaño de la ventana en que esta siendo redimensionada.details
Objectedge
(string) - El borde de la ventana siendo arrastrada para cambiar el tamaño. Puede serbottom
,left
,right
,top-left
,top-right
,bottom-left
obottom-right
.
Emitido antes de que la ventana sea redimensionada. Llamar a event.preventDefault()
evitará que la ventana sea redimensionada.
Tenga en cuenta que esto solo es emitido cuando la venta está siendo redimensionada de forma manual. Redimensionar la ventana con setBounds
/setSize
no emitirá este evento.
Los posibles valores y comportamientos de la opción edge
son dependientes de la plataforma. Los valores posibles son:
- En Windows, los posibles valores son
bottom
,top
,left
,right
,top-left
,top-right
,bottom-left
,bottom-right
. - En macOS, los posibles valores son
bottom
yright
.- El valor
bottom
es usado para denotar un cambio de tamaño vertical. - El valor
right
es usado para denotar un cambio de tamaño horizontal.
- El valor
Evento: "resize"
Emitido después que la ventana se haya redimensionada.
Evento: 'resized' macOS Windows
Emitted once when the window has finished being resized.
This is usually emitted when the window has been resized manually. On macOS, resizing the window with setBounds
/setSize
and setting the animate
parameter to true
will also emit this event once resizing has finished.
Evento: 'will-move' macOS Windows
Devuelve:
event
newBounds
Rectangle - Ubicación a la que se está moviendo la ventana.
Emitted before the window is moved. On Windows, calling event.preventDefault()
will prevent the window from being moved.
Note that this is only emitted when the window is being moved manually. Moving the window with setPosition
/setBounds
/center
will not emit this event.
Evento: "move"
Aparece cuando la ventana se mueve a una nueva posición.
Evento: 'moved' macOS Windows
Aparece solo una vez cuando la ventana se mueve a una nueva posición.
Note: En macOS este evento es un alias de move
.
Evento: "enter-full-screen"
Aparece cuando la ventana entra en un estado pantalla completa.
Evento: "leave-full-screen"
Aparece cuando la ventana sale del estado pantalla completa.
Evento: "enter-html-full-screen"
Aparece cuando la ventana entra en un estado pantalla completa activado por la API HTML.
Evento: "leave-html-full-screen"
Aparece cuando la ventana sale de un estado pantalla completa activado por la API HTML.
Evento: 'always-on-top-changed'
Devuelve:
event
isAlwaysOnTop
boolean
Emitido cuando la ventana es configurada o no configurada para mostrarse siempre en la parte superior de las otras ventanas.
Evento: 'app-command' Windows Linux
Devuelve:
event
command
cadena
Aparece cuando se invoca un App Command. Estos están generalmente relacionados a las teclas del teclado o a los comandos del navegador, así como el botón "Back" está en algunos ratones en Windows.
Los comandos están en minuscula, los guiones bajos son remplazados por guiones, y el prefijo APPCOMMAND_
se elimina. por ejemplo, APPCOMMAND_BROWSER_BACKWARD
aparece como browser-backward
.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.on('app-command', (e, cmd) => {
// Navigate the window back when the user hits their mouse back button
if (cmd === 'browser-backward' && win.webContents.canGoBack()) {
win.webContents.goBack()
}
})
Los siguientes comandos de aplicación están explícitamente soportados en Linux:
browser-backward
browser-forward
Evento: "swipe" macOS
Devuelve:
event
direction
string
Emitted on 3-finger swipe. Possible directions are up
, right
, down
, left
.
El método subyacente a este evento esta construido para manejar el viejo estilo de desplazamiento del trackpad de macOS, donde el contenido de la pantalla no se mueve con el manotazo. La mayoría de los trackpads de macOS ya no están configurados para permitir este tipo de movimiento, así que para emitir correctamente la preferencia 'Desplazamiento entre paginas' en System Preferences > Trackpad > More Gestures
debe establecer a 'Desplazar con dos o tres dedos'.
Evento: 'rotate-gesture' macOS
Devuelve:
event
rotation
Float
Emitido en el gesto de rotación de trackpad. Continuamente emitido hasta que el gesto de rotación se termine. El valor rotation
en cada emisión es el angulo rotado en grado desde la última emisión. El último evento emitido sobre un gesto de rotación será siempre de valor 0
. Los valores de rotación en sentido antihorario son positivos, mientras que los valores de rotación en sentido horario son negativos.
Evento: "sheet-begin" macOS
Aparece cuando la ventana abre una hoja.
Evento: "sheet-end" macOS
Aparece cuando la ventana cierra una hoja.
Evento: "new-window-for-tab" macOS
Aparece cuando se hace clic al botón de nueva pestaña nativa.
Evento: 'system-context-menu' Windows
Devuelve:
event
point
Point - Las coordenadas de la pantalla del menú contextual que fue activado en
Emitido cuando el menú contextual del sistema es activado en la ventana, esto normalmente solo es activado cuando el usuario hace click derecho en el área que no es del cliente de la ventana. Esto es la barra de titulo de la ventana o cualquier área que haya declarado como -webkit-app-region: drag
en una ventana sin marco.
Llamando a event.preventDefault()
evitara que el menú sea mostrado.
Métodos Estáticos
La clase BrowserWindow
tiene los siguientes métodos estáticos:
BrowserWindow.getAllWindows()
Devuelve BrowserWindow[]
- Un arreglo de todas las ventanas abiertas del navegador.
BrowserWindow.getFocusedWindow()
Devuelve BrowserWindow | null
- La ventana que es enfocada en esta aplicación, de lo contrario devuelve null
.
BrowserWindow.fromWebContents(webContents)
webContents
WebContents
Devuelve BrowserWindow | null
- La ventana a que pertenece el webContents
indicado o null
si los contenidos no son propiedad de una ventana.
BrowserWindow.fromBrowserView(browserView)
Obsoleto
browserView
BrowserView
Note The
BrowserView
class is deprecated, and replaced by the newWebContentsView
class.
Devuelve BrowserWindow | null
- La ventana que posee el browserView
dado. Si la vista dada no esta adjunta a ninguna ventana, devuelve null
.
BrowserWindow.fromId(id)
id
Íntegro
Devuelve BrowserWindow | null
-La ventana con la id
especificada.
Propiedades de la instancia
Los objetos creados con new BrowserWindow
tienen las siguientes propiedades:
const { BrowserWindow } = require('electron')
// In this example `win` is our instance
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')
win.webContents
SoloLectura
Un objeto WebContents
que esta ventana posse. Toda página web relacionada eventos y operaciones se realizarán a través de ella.
Consulte la documentation webContents
de sus métodos y eventos.
win.id
SoloLectura
Una propiedad Integer
representando el identificador único de la ventana. Cada ID es único entre todas las instancias BrowserWindow
de toda la aplicación Electron.
win.tabbingIdentifier
macOS Readonly
A string
(optional) property that is equal to the tabbingIdentifier
passed to the BrowserWindow
constructor or undefined
if none was set.
win.autoHideMenuBar
Una propiedad boolean
que determina si la barra de menú de la ventana debe ocultarse automáticamente. Una vez activada, la barra de menú sólo se mostrará cuando los usuarios presionen la tecla Alt
.
Si la barra de menú ya está visible, estableciendo esta propiedad a true
no la ocultara inmediatamente.
win.simpleFullScreen
A boolean
property that determines whether the window is in simple (pre-Lion) fullscreen mode.
win.fullScreen
A boolean
property that determines whether the window is in fullscreen mode.
win.focusable
Windows macOS
Una propiedad boolean
que determina si la ventana es enfocable.
win.visibleOnAllWorkspaces
macOS Linux
A boolean
property that determines whether the window is visible on all workspaces.
Nota: Siempre devuelve false en Windows.
win.shadow
A boolean
property that determines whether the window has a shadow.
win.menuBarVisible
Windows Linux
A boolean
property that determines whether the menu bar should be visible.
Note: If the menu bar is auto-hide, users can still bring up the menu bar by pressing the single Alt
key.
win.kiosk
A boolean
property that determines whether the window is in kiosk mode.
win.documentEdited
macOS
A boolean
property that specifies whether the window’s document has been edited.
The icon in title bar will become gray when set to true
.
win.representedFilename
macOS
A string
property that determines the pathname of the file the window represents, and the icon of the file will show in window's title bar.
win.title
A string
property that determines the title of the native window.
Note: The title of the web page can be different from the title of the native window.
win.minimizable
macOS Windows
Una propiedad boolean
que determina si la ventana puede ser minimizada manualmente por el usuario.
En Linux el setter no es operativo, a pesar de que el getter devuelve true
.
win.maximizable
macOS Windows
Una propiedad boolean
que determina si la ventana puede ser maximizada manualmente por el usuario.
En Linux el setter no es operativo, a pesar de que el getter devuelve true
.
win.fullScreenable
Una propiedad boolean
que determina si los botones de la ventana maximizar/ampliar alterna el modo de pantalla completa o maximiza la ventana.
win.resizable
Una propiedad boolean
que determina si la ventana puede ser redimencionada manualmente por el usuario.
win.closable
macOS Windows
Una propiedad boolean
que determina si la ventana puede ser cerrada manualmente por el usuario.
En Linux el setter no es operativo, a pesar de que el getter devuelve true
.
win.movable
macOS Windows
Una propiedad boolean
que determina si la ventana puede ser movida por el usuario.
En Linux el setter no es operativo, a pesar de que el getter devuelve true
.
win.excludedFromShownWindowsMenu
macOS
Una propiedad boolean
que determina si la ventana es excluida o no del menu Windows de la aplicación. false
por defecto.
const win = new BrowserWindow({ height: 600, width: 600 })
const template = [
{
role: 'windowmenu'
}
]
win.excludedFromShownWindowsMenu = true
const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)
win.accessibleTitle
A string
property that defines an alternative title provided only to accessibility tools such as screen readers. Esta cadena no es directamente visible para los usuarios.
Métodos de Instancia
Los objetos creados con new BrowserWindow
tienen los siguientes métodos de instancia:
Note: Algunos métodos solo están disponibles en sistemas operativos específicos y son etiquetados como tal.
win.destroy()
Al forzar el cierre de una ventana, el evento unload
y beforeunload
no se emitirá en la página web. El evento close
tampoco se emitirá en la ventana, pero es seguro que el evento closed
sí será emitido.
win.close()
Trate de cerrar la ventana. Esto tiene el mismo efecto que un usuario pulsando manualmente el botón cerrar de la ventana. The web page may cancel the close though. Ver el close event.
win.focus()
Enfoca la ventana.
win.blur()
Elimina el enfoque de la ventana.
win.isFocused()
Devuelve boolean
- Si la ventana está centrada o no.
win.isDestroyed()
Devuelve boolean
- Si la ventana fue destruida o no.
win.show()
Muestra la ventana y la enfoca.
win.showInactive()
Muestra la ventana pero no la enfoca.
win.hide()
Oculta la ventana.
win.isVisible()
Returns boolean
- Whether the window is visible to the user in the foreground of the app.
win.isModal()
Devuelve boolean
- Si la ventana actual es una ventana modal o no.
win.maximize()
Maximiza la ventana. This will also show (but not focus) the window if it isn't being displayed already.
win.unmaximize()
Sale del estado maximizado de la ventana.
win.isMaximized()
Devuelve boolean
- Si la ventana está maximizada.
win.minimize()
Minimiza la ventana. On some platforms the minimized window will be shown in the Dock.
win.restore()
Restaura la ventana desde un estado minimizado a su estado previo.
win.isMinimized()
Devuelve boolean
- Si la ventana está minimizada o no.
win.setFullScreen(flag)
flag
boolean
Establece si la ventana debe estar o no en modo pantalla completa.
Note: On macOS, fullscreen transitions take place asynchronously. If further actions depend on the fullscreen state, use the 'enter-full-screen' or 'leave-full-screen' events.
win.isFullScreen()
Devuelve boolean
- Si la ventana está o no en pantalla completa.
Note: On macOS, fullscreen transitions take place asynchronously. When querying for a BrowserWindow's fullscreen status, you should ensure that either the 'enter-full-screen' or 'leave-full-screen' events have been emitted.
win.setSimpleFullScreen(flag)
macOS
flag
boolean
Entra o sale del modo simple de pantalla completa.
Simple fullscreen mode emulates the native fullscreen behavior found in versions of macOS prior to Lion (10.7).
win.isSimpleFullScreen()
macOS
Devuelve boolean
- Si la ventana está en modo simple de pantalla completa (pre-Lion).
win.isNormal()
Devuelve boolean
- Si la ventana esta en estado normal (no maximizada, no minimizada, no en el modo de pantalla completa).
win.setAspectRatio(aspectRatio[, extraSize])
aspectRatio
Flotador - La relación de aspecto para mantener parte de la vista de contenido.extraSize
Size (optional) macOS - The extra size not to be included while maintaining the aspect ratio.
Esto hará que la ventana mantenga una relación de aspecto. El tamaño extra permite al desarrollador tener espacio especificado en píxeles, el cual no está incluido dentro de los cálculos de la relación de aspecto. Esta API ya toma en cuenta la diferencia entre el tamaño de la ventana y el tamaño del contenido.
Considere una ventana normal con un reproductor de video HD y los controles asociados. Quizá hay 15 pixeles de controles en el borde izquierdo, 25 pixeles de control en el borde derecho y 50 pixeles de control bajo el reproductor. Para mantener una relación de aspecto 16:9 (relación de aspecto estándar para HD @1920x1080) dentro del reproductor tendríamos que llamar esta función con argumentos de 16/9 y { width: 40, height: 50 . En el segundo argumento no importa donde están la anchura extra ni altura extra dentro de la vista del contenido, solo importa que existan. Suma cualquier áreas de ancho y alto adicionales que tengas dentro de la vista de contenido general.
La relación de aspecto no se respeta cuando la ventana se redimensiona programáticamente con APIs como win.setSize
.
To reset an aspect ratio, pass 0 as the aspectRatio
value: win.setAspectRatio(0)
.
win.setBackgroundColor(backgroundColor)
backgroundColor
string - Color in Hex, RGB, RGBA, HSL, HSLA or named CSS color format. The alpha channel is optional for the hex type.
Ejemplos de valores válidos de backgroundColor
:
- Hex
- #fff (shorthand RGB)
- #ffff (shorthand ARGB)
- #ffffff (RGB)
- #ffffffff (ARGB)
- RGB
rgb\(([\d]+),\s*([\d]+),\s*([\d]+)\)
- ej. rgb(255, 255, 255)
- RGBA
rgba\(([\d]+),\s*([\d]+),\s*([\d]+),\s*([\d.]+)\)
- ej. rgba(255, 255, 255, 1.0)
- HSL
hsl\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%\)
- ej. hsl(200, 20%, 50%)
- HSLA
hsla\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%,\s*([\d.]+)\)
- ej. hsla(200, 20%, 50%, 0.5)
- Nombre de color
- Las opciones se enumeran en SkParseColor.cpp
- Similar a las palabras clave del Módulo de Color CSS Nivel 3, pero sensible a mayúsculas y minúsculas.
- ej.
blueviolet
ored
- ej.
Establece el color de fondo de la ventana. See Setting backgroundColor
.
win.previewFile(path[, displayName])
macOS
path
cadena - La ruta de acceso absoluta al archivo para vista previa con QuickLook. Esto es importante a medida que Quick Look utiliza el nombre del archivo y la extensión del archivo en la ruta para determinar el tipo de contenido del archivo que se va a abrir.displayName
cadena (opcional) - El nombre del archivo a mostrar en la vista modal de Quick Look. Esto es puramente visual y no afecta el tipo de contenido del archivo. Por defecto espath
.
Utiliza Quick Look para previsualizar un archivo de una ruta determinada.
win.closeFilePreview()
macOS
Cierra el panel actual de Quick Look.
win.setBounds(bounds[, animate])
bounds
Partial<Rectangle>animate
booleano (opcional) macOS
Redimensiona y mueve la ventana a los límites proporcionados. Cualquier propiedad que no se proporcione tendrá sus valores actuales por defecto.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
// set all bounds properties
win.setBounds({ x: 440, y: 225, width: 800, height: 600 })
// set a single bounds property
win.setBounds({ width: 100 })
// { x: 440, y: 225, width: 100, height: 600 }
console.log(win.getBounds())
Note: On macOS, the y-coordinate value cannot be smaller than the Tray height. The tray height has changed over time and depends on the operating system, but is between 20-40px. Passing a value lower than the tray height will result in a window that is flush to the tray.
win.getBounds()
Retorna Rectangle - El bounds
de la ventana como Object
.
Note: On macOS, the y-coordinate value returned will be at minimum the Tray height. For example, calling win.setBounds({ x: 25, y: 20, width: 800, height: 600 })
with a tray height of 38 means that win.getBounds()
will return { x: 25, y: 38, width: 800, height: 600 }
.
win.getBackgroundColor()
Devuelve string
- Obtiene el color de fondo de la ventana en formato Hex (#RRGGBB
).
Note: The alpha value is not returned alongside the red, green, and blue values.
win.setContentBounds(bounds[, animate])
bounds
Rectangleanimate
booleano (opcional) macOS
Redimensiona y mueve el área del cliente de la ventana (por ejemplo, la página web) hasta los límites proporcionados.
win.getContentBounds()
Retorna Rectangle - El bounds
del área del cliente de la ventana como Object
.
win.getNormalBounds()
Devuelve Rectangle - Contiene los limites del estado normal de la ventana
Note: si el estado actual de la ventana: maximizado, minimizado en el pantalla completa, esta función siempre devuelve la posición y tamaño de la ventana en estado normal. En estado normal, getBounds y getNormalBounds el mismo Rectangle.
win.setEnabled(enable)
enable
boolean
Habilita o deshabilita la ventana.
win.isEnabled()
Devuelce boolean
-si la ventana está activada.
win.setSize(width, height[, animate])
width
Integeralto
Integeranimate
booleano (opcional) macOS
Cambia el tamaño de la ventana a width
y height
. If width
or height
are below any set minimum size constraints the window will snap to its minimum size.
win.getSize()
Devuelve Integer[]
- Contiene la anchura y altura de la ventana.
win.setContentSize(width, height[, animate])
width
Integeralto
Integeranimate
booleano (opcional) macOS
Cambia el área del cliente de la ventana (por ejemplo, la página web) a la width
y height
.
win.getContentSize()
Devuelve Integer[]
- Contiene la anchura y altura del área del cliente de la ventana.
win.setMinimumSize(width, height)
width
Integeralto
Integer
Establece el tamaño mínimo de la ventana a width
y height
.
win.getMinimumSize()
Devuelve Integer[]
- Contiene la anchura y altura mínima de la ventana.
win.setMaximumSize(width, height)
width
Integeralto
Integer
Establece el tamaño máximo de la ventana a width
y height
.
win.getMaximumSize()
Devuelve Integer[]
- Contiene la anchura y altura máxima de la ventana.
win.setResizable(resizable)
resizable
boolean
Sets whether the window can be manually resized by the user.
win.isResizable()
Devuelve boolean
- Si la ventana puede ser manualmente redimensionada por el usuario.
win.setMovable(movable)
macOS Windows
movable
boolean
Sets whether the window can be moved by user. En Linux no hace nada.
win.isMovable()
macOS Windows
Devuelve boolean
- Si la ventana puede ser movida por el usuario.
En Linux siempre devuelve true
.
win.setMinimizable(minimizable)
macOS Windows
minimizable
boolean
Sets whether the window can be manually minimized by user. En Linux no hace nada.
win.isMinimizable()
macOS Windows
Devuelve boolean
- Si la ventana puede ser manualmente minimizada por el usuario.
En Linux siempre devuelve true
.
win.setMaximizable(maximizable)
macOS Windows
maximizable
boolean
Sets whether the window can be manually maximized by user. En Linux no hace nada.
win.isMaximizable()
macOS Windows
Devuelve boolean
- Si la ventana puede ser maximizada manualmente por el usuario.
En Linux siempre devuelve true
.
win.setFullScreenable(fullscreenable)
fullscreenable
boolean
Sets whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
win.isFullScreenable()
Returns boolean
- Whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.
win.setClosable(closable)
macOS Windows
closable
boolean
Sets whether the window can be manually closed by user. En Linux no hace nada.
win.isClosable()
macOS Windows
Devuelve boolean
- Si la ventana puede ser o no cerrada manualmente por el usuario.
En Linux siempre devuelve true
.
win.setHiddenInMissionControl(hidden)
macOS
hidden
boolean
Sets whether the window will be hidden when the user toggles into mission control.
win.isHiddenInMissionControl()
macOS
Returns boolean
- Whether the window will be hidden when the user toggles into mission control.
win.setAlwaysOnTop(flag[, level][, relativeLevel])
flag
booleanlevel
string (opcional) macOS Windows - Valores incluyennormal
,floating
,torn-off-menu
,modal-panel
,main-menu
,status
,pop-up-menu
,screen-saver
, y(Obsoleto). Por defecto esdock
floating
cuandoflag
es true. Ellevel
se restablece anormal
cuando la bandera es false. Tenga en cuenta que desdefloating
astatus
incluido, la venta está colocada debajo del Dock en macOS y debajo de la barra de tarea en Windows. Desdepop-up-menu
a un superior se muestra sobre el Dock en macOS y sobre la barra de tareas en Windows. Vea la macOS docs para más detalles.relativeLevel
Integer (opcional) macOS - El número de capas más alto para configurar esta ventana con respecto allevel
determinado. Por defecto es0
. Tenga en cuenta que Apple desalienta establecer niveles superiores a 1 sobrescreen-saver
.
Sets whether the window should show always on top of other windows. Después de configurar esto, la ventana seguirá siendo una ventana normal, y no una ventana de herramientas que no puede enfocarse.
win.isAlwaysOnTop()
Devuelve boolean
- Si la ventana está siempre sobre las otras ventanas.
win.moveAbove(mediaSourceId)
mediaSourceId
string - Window id in the format of DesktopCapturerSource's id. Por ejemplo "window:1869:0".
Moves window above the source window in the sense of z-order. If the mediaSourceId
is not of type window or if the window does not exist then this method throws an error.
win.moveTop()
Mover ventana a la parte superior(z-order) independientemente del enfoque
win.center()
Mueve la ventana al centro de la pantalla.
win.setPosition(x, y[, animate])
x
Integery
Integeranimate
booleano (opcional) macOS
Mueve la ventana a x
y y
.
win.getPosition()
Devuelve Integer[]
- Contiene la posición actual de la ventana.
win.setTitle(title)
title
string
Cambia el título de la ventana nativa a title
.
win.getTitle()
Devuelve string
- El título de la ventana nativa.
Note: El título de la página web puede ser diferente del título de la ventana nativa.
win.setSheetOffset(offsetY[, offsetX])
macOS
offsetY
FloatoffsetX
Float (opcional)
Changes the attachment point for sheets on macOS. By default, sheets are attached just below the window frame, but you may want to display them beneath a HTML-rendered toolbar. Por ejemplo:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
const toolbarRect = document.getElementById('toolbar').getBoundingClientRect()
win.setSheetOffset(toolbarRect.height)
win.flashFrame(flag)
History
Version(s) | Changes |
---|---|
None |
|
flag
boolean
Empieza y deja de hacer parpadear la ventana para atraer la atención del usuario.
win.setSkipTaskbar(skip)
macOS Windows
skip
booleano
Hace que la ventana no se muestre en la barra de tareas.
win.setKiosk(flag)
flag
boolean
Entra / sale del modo Kiosko.
win.isKiosk()
Devuelve boolean
- Si la ventana está o no en modo kiosco.
win.isTabletMode()
Windows
Devuelve boolean
- Si la ventana está en modo tableta de Windows 10.
Since Windows 10 users can use their PC as tablet, under this mode apps can choose to optimize their UI for tablets, such as enlarging the titlebar and hiding titlebar buttons.
Esta API devuelve si la ventana esta en modo tableta y el evento resize
puede ser usado para escuchar los cambios en el modo tableta.
win.getMediaSourceId()
Devuelve string
- El identificador de la ventana en formato de identificador de DesktopCapturerSource. Por ejemplo "window:1324:0".
Más específicamente el formato es window:id:other_id
donde id
es HWND
en Windows, CGWindowID
(uint64_t
) en macOS y Window
(unsigned long
) en Linux. other_id
es usado para identificar contenidos webs (pestañas) así dentro de la misma ventana de nivel superior.
win.getNativeWindowHandle()
Devuelve Buffer
- El controlador específico de la plataforma de la ventana.
El tipo nativo del controlador en Windows es HWND
, en macOS NSView*
y en Linux Window
(unsigned long
).
win.hookWindowMessage(message, callback)
Windows
message
Integercallback
FunctionwParam
Buffer - ThewParam
provided to the WndProclParam
Buffer - ThelParam
provided to the WndProc
Engancha una ventana de mensaje. The callback
is called when the message is received in the WndProc.
win.isWindowMessageHooked(message)
Windows
message
Integer
Devuelve boolean
- true
o false
dependiendo de si el mensaje esta anclado o no.
win.unhookWindowMessage(message)
Windows
message
Integer
Desancla el mensaje de la ventana.
win.unhookAllWindowMessages()
Windows
Desancla todos los mensajes de la ventana.
win.setRepresentedFilename(filename)
macOS
filename
string
Establece el nombre de la ruta del archivo que la ventana representa, y el icono del archivo se mostrará en la barra de título de la ventana.
win.getRepresentedFilename()
macOS
Devuelve string
- El nombre de la ruta del archivo que la ventana representa.
win.setDocumentEdited(edited)
macOS
edited
boolean
Especifica si se ha editado el documento de la ventana y el icono en la barra de título se volverá gris cuando se establece en true
.
win.isDocumentEdited()
macOS
Devuelve boolean
- Si se ha editado el documento de la ventana.
win.focusOnWebView()
win.blurWebView()
win.capturePage([rect, opts])
rect
Rectangle (opcional) - Los límites para capturaropts
Object (optional)stayHidden
boolean (opcional) - Mantiene la página oculta en lugar de visible. Por defecto esfalse
.stayAwake
boolean (optional) - Keep the system awake instead of allowing it to sleep. Por defecto esfalse
.
Devuelve Promise<NativeImage>
- Resuelve con el un NativeImage
Captura una foto instantánea de la página dentro de rect
. Omitir rect
capturará toda la página visible. Si la página no es visible, rect
puede estar vacía. The page is considered visible when its browser window is hidden and the capturer count is non-zero. Si le gustaría que la página permanezca oculta, debería asegurarse que stayHidden
está establecido a true.
win.loadURL(url[, options])
url
string
Devuelve Promise<void>
- la promesa sera resolvida cuando la página haya finalizado de cargar (mira did-finish-load
), y será rechazada si la pagina falla al cargar (mira did-fail-load
).
Igual que webContents.loadURL(url[, opciones])
.
El url
puede ser una dirección remota (por ejemplo http://
) o una de un archivo locar HTML utilizando el protocolo file://
.
Para garantizar que los URLs del archivo estén adecuadamente formateados, se recomienda utilizar el método url.format
del Nodo:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
const url = require('url').format({
protocol: 'file',
slashes: true,
pathname: require('node:path').join(__dirname, 'index.html')
})
win.loadURL(url)
Se puede cargar un URL utilizando la solicitud POST
con los datos codificados de URL haciendo lo siguiente:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.loadURL('http://localhost:8000/post', {
postData: [{
type: 'rawData',
bytes: Buffer.from('hello=world')
}],
extraHeaders: 'Content-Type: application/x-www-form-urlencoded'
})
win.loadFile(filePath[, options])
filePath
string
Devuelve Promise<void>
- la promesa sera resolvida cuando la página haya finalizado de cargar (mira did-finish-load
), y será rechazada si la pagina falla al cargar (mira did-fail-load
).
Same as webContents.loadFile
, filePath
should be a path to an HTML file relative to the root of your application. Ver la documentación webContents
para más información.
win.reload()
Es igual a webContents.reload
.
win.setMenu(menu)
Linux Windows
menu
Menu | null
Establece el menu
como el menu bar de la ventana.
win.removeMenu()
Linux Windows
Eliminar la barra de menú de la ventana.
win.setProgressBar(progress[, options])
progress
Double
Establece el valor del progreso en el progress bar. Valid range is [0, 1.0].
Elimina la barra de progreso cuando el progreso es < 0; cambia a modo indeterminado cuando el progreso es >1.
En la plataforma Linux, solo es compatible con el environment de escritorio Unity. Se necesita especificar el nombre del archivo *.desktop
en el campo desktopName
dentro de package.json
. Por defecto asumirá {app.name}.desktop
.
En Windows, se puede pasar de modo. Los valores aceptados son none
, normal
, indeterminate
, error
, y paused
. Si se llama asetProgressBar
sin establecer un modo (pero con un valor dentro del rango válido), se asumirá el modo normal
.
win.setOverlayIcon(overlay, description)
Windows
overlay
NativeImage | null - el icono a mostrar en la parte inferior derecha del icono de la barra de tareas. Si este parámetro esnull
, se borra la superposicióndescription
cadena- una descripción que se facilitará a los lectores de la pantalla Accessibility
Establece una superposición de 16 x 16 píxeles sobre el icono actual de la barra de tareas. Generalmente se utiliza para transmitir algún tipo de estatus de la aplicación o para notificar pasivamente al usuario.
win.invalidateShadow()
macOS
Invalidates the window shadow so that it is recomputed based on the current window shape.
BrowserWindows
that are transparent can sometimes leave behind visual artifacts on macOS. This method can be used to clear these artifacts when, for example, performing an animation.
win.setHasShadow(hasShadow)
hasShadow
boolean
Establece si la ventana debe tener una sombra.
win.hasShadow()
Devuelve boolean
- Si la ventana tiene o no una sombra.
win.setOpacity(opacity)
Windows macOS
opacity
number- entre 0.0 (completamente transparente) y 1.0 (completamente opaco)
Establece la opacidad de la ventana. En Linux no hace nada. Out of bound number values are clamped to the [0, 1] range.
win.getOpacity()
Devuelve number
- entre 0.0 (completamente transparente) y 1.0 (completamente opaco). En Linux, siempre devuelve 1.
win.setShape(rects)
Windows Linux Experimental
rects
Rectangle[] - Sets a shape on the window. Passing an empty list reverts the window to being rectangular.
Establecer una forma de ventana determina el área dentro de la ventana donde el sistema permite dibujar y interactuar con el usuario. Fuera de la región dada, no se dibujarán píxeles y no se registrarán eventos del ratón. Los eventos del ratón fuera de la región no será recibida por esa ventana, pero pasará a lo que esté detrás de la misma.
win.setThumbarButtons(buttons)
Windows
buttons
ThumbarButton[]
Devuelve boolean
- Si los botones se añadieron o no exitosamente
Añade la barra de herramientas de la vista previa con una configuración específica de los botones para la imagen previsualizada de una ventana en el plano del botón en la barra de tareas. Devuelve un objeto boolean
e indica si la previsualización se ha agregado con éxito.
El número de botones en la barra de herramientas de la vista previa no debe ser mayor que 7 debido al limitado espacio. Una vez que se configura la barra de herramientas de la vista previa, la barra de tareas no puede ser eliminada debido a las limitaciones de la plataforma. Sin embargo, se puede llamar a la API con un arreglo vacío para limpiar los botones.
Los buttons
es un arreglo de objetos Button
:
- Objeto
Button
icon
NativeImage - El icono mostrado en miniatura.click
Funcióntooltip
string (opcional): el texto de la información sobre el botón.flags
string[] (opcional) - Controla los estados y comportamientos específicos del botón. Por defecto, es['enabled']
.
Los flags
es una matriz que puede incluir siguientes string
s:
enabled
- El botón está activo y disponible para el usuario.disabled
- El botón está deshabilitado. Está presente, pero tiene un estado visual indicando que no responderá a la acción del usuario.dismissonclick
- Cuando se hace clic en el botón, la ventana de miniatura se cierra de inmediato.nobackground
- No dibuja un borde del botón, usa solo la imagen.hidden
- El botón no es mostrado al usuario.noninteractive
- El botón está habilitado pero no es interactivo; no se dibuja el estado del botón pulsado. Este valor está destinado a instancias donde el botón se utiliza en una notificación.
win.setThumbnailClip(region)
Windows
region
Rectangle - la región de la ventana
Establece la región de la ventana para mostrar como la vista previa de la imagen es mostrada cuando se pasa sobre la ventana en la barra de tareas. Puede restablecer la miniatura de la la ventana completa simplemente especificando una región vacía: { x: 0, y: 0, width: 0, height: 0 }
.
win.setThumbnailToolTip(toolTip)
Windows
toolTip
string
Configura la descripción emergente que se muestra cuando se pasa sobre la vista previa de la ventana en la barra de tareas.
win.setAppDetails(options)
Windows
Establece las propiedades para el botón de la barra de herramientas de la ventana.
Note: relaunchCommand
y relaunchDisplayName
siempre deben ser establecidos juntos. Si una de esas propiedades no está establecida, entonces ninguna será usada.
win.showDefinitionForSelection()
macOS
Es igual a webContents.showDefinitionForSelection()
.
win.setIcon(icon)
Windows Linux
icon
NativeImage | string
Cambia el icono de la ventana.
win.setWindowButtonVisibility(visible)
macOS
visible
boolean
Establece si los botones de luz del tráfico de ventana deben estar visibles.
win.setAutoHideMenuBar(hide)
Windows Linux
hide
boolean
Establece si el menu bar de la ventana debe ocultarse a si misma automáticamente o no. Once set the menu bar will only show when users press the single Alt
key.
If the menu bar is already visible, calling setAutoHideMenuBar(true)
won't hide it immediately.
win.isMenuBarAutoHide()
Windows Linux
Devuelve boolean
- Si la barra de menú se oculta o no automáticamente.
win.setMenuBarVisibility(visible)
Windows Linux
visible
boolean
Establece si la barra de menú debe estar visible. If the menu bar is auto-hide, users can still bring up the menu bar by pressing the single Alt
key.
win.isMenuBarVisible()
Windows Linux
Devuelve boolean
- Si la barra de menú es visible o no.
win.setVisibleOnAllWorkspaces(visible[, options])
macOS Linux
visible
boolean
Establece si la ventana debe ser visible o no en todos los espacios de trabajo.
Nota: Esta API no hace nada en Windows.
win.isVisibleOnAllWorkspaces()
macOS Linux
Devuelve boolean
- Si la ventana es visible en todos los espacios de trabajo.
Nota: Esta API siempre devuelve false en Windows.
win.setIgnoreMouseEvents(ignore[, options])
ignore
boolean
Hace que la ventana ignore todos los eventos del ratón.
Todos los eventos del ratón ocurridos en esta ventana se pasarán a la ventana debajo de esta ventana, pero si esta ventana esta enfocada, todavía recibirá los eventos del teclado.
win.setContentProtection(enable)
macOS Windows
enable
boolean
Evita que los contenidos de la ventana sean capturados por otras aplicaciones.
On macOS it sets the NSWindow's sharingType to NSWindowSharingNone. On Windows it calls SetWindowDisplayAffinity with WDA_EXCLUDEFROMCAPTURE
. For Windows 10 version 2004 and up the window will be removed from capture entirely, older Windows versions behave as if WDA_MONITOR
is applied capturing a black window.
win.setFocusable(focusable)
macOS Windows
focusable
boolean
Cambia si se puede enfocar o no la ventana.
En macOS no elimina el foco de la ventana.
win.isFocusable()
macOS Windows
Returns boolean
- Whether the window can be focused.
win.setParentWindow(parent)
parent
BrowserWindow | null
Establece parent
como la ventana de la ventana principal actual. Al pasar null
cambiará la ventana actual a una ventana de nivel superior.
win.getParentWindow()
Devuelve BrowserWindow | null
- La ventana padre o null
si no hay padre.
win.getChildWindows()
Devuelve BrowserWindow[]
- Todas las ventanas secundarias.
win.setAutoHideCursor(autoHide)
macOS
autoHide
boolean
Controla si se debe ocultar el cursor al escribir.
win.selectPreviousTab()
macOS
Selecciona la pestaña previa cuando las pestañas nativas están activas y hay otras pestañas en la ventana.
win.selectNextTab()
macOS
Selecciona la siguiente pestaña cuando las pestañas nativas están activas y hay otras pestañas en la ventana.
win.showAllTabs()
macOS
Shows or hides the tab overview when native tabs are enabled.
win.mergeAllWindows()
macOS
Unifica todas las ventanas en una sola con múltiples pestañas cuando las pestañas nativas están activas y hay más de una ventana abierta.
win.moveTabToNewWindow()
macOS
Mueve la pestaña actual a una nueva ventana si las pestañas nativas están activas y hay más de una pestaña en la ventana actual.
win.toggleTabBar()
macOS
Conmuta la visibilidad de la barra de pestañas si las pestañas nativas están activas y hay solo una pestaña en la ventana actual.
win.addTabbedWindow(browserWindow)
macOS
browserWindow
BrowserWindow
Añade una ventana como pestaña de la ventana actual, después de la pestaña para la instancia de la ventana actual.
win.setVibrancy(type)
macOS
type
string | null - Can betitlebar
,selection
,menu
,popover
,sidebar
,header
,sheet
,window
,hud
,fullscreen-ui
,tooltip
,content
,under-window
, orunder-page
. Para más detalles, ver macOS documentation.
Añade un efecto de vibración a la ventana del navegador. Passing null
or an empty string will remove the vibrancy effect on the window.
win.setBackgroundMaterial(material)
Windows
material
stringauto
- Let the Desktop Window Manager (DWM) automatically decide the system-drawn backdrop material for this window. Este es el valor predeterminado.none
- Don't draw any system backdrop.mica
- Draw the backdrop material effect corresponding to a long-lived window.acrylic
- Draw the backdrop material effect corresponding to a transient window.tabbed
- Draw the backdrop material effect corresponding to a window with a tabbed title bar.
This method sets the browser window's system-drawn background material, including behind the non-client area.
See the Windows documentation for more details.
Note: This method is only supported on Windows 11 22H2 and up.
win.setWindowButtonPosition(position)
macOS
position
Point | null
Establece una posición personalizada para los botones del semáforo en la ventana sin marco. Passing null
will reset the position to default.
win.getWindowButtonPosition()
macOS
Returns Point | null
- The custom position for the traffic light buttons in frameless window, null
will be returned when there is no custom position.
win.setTouchBar(touchBar)
macOS
touchBar
TouchBar | null
Configura el plano de la touchBar para la ventana actual. Espeficando null
o undefined
elimina la barra táctil. This method only has an effect if the machine has a touch bar.
Nota: La API TouchBar API actualmente es experimental y puede cambiar o ser eliminada en futuras versiones de Electron.
win.setBrowserView(browserView)
Experimental Obsoleto
browserView
BrowserView | null - AdjuntabrowserView
awin
. Si hay otrosBrowserView
s adjuntos, se eliminarán de esta ventana.
Note The
BrowserView
class is deprecated, and replaced by the newWebContentsView
class.
win.getBrowserView()
Experimental Obsoleto
Devuelve BrowserView | null
- El BrowserView
adjunto a win
. Devuelve null
si uno no esta adjunto. Lanza un error si múltiples BrowserView
son adjuntos.
Note The
BrowserView
class is deprecated, and replaced by the newWebContentsView
class.
win.addBrowserView(browserView)
Experimental Obsoleto
browserView
BrowserView
API de reemplazo para setBrowserView soporta el trabajo con múltiples vistas de navegador.
Note The
BrowserView
class is deprecated, and replaced by the newWebContentsView
class.
win.removeBrowserView(browserView)
Experimental Obsoleto
browserView
BrowserView
Note The
BrowserView
class is deprecated, and replaced by the newWebContentsView
class.
win.setTopBrowserView(browserView)
Experimental Obsoleto
browserView
BrowserView
Levanta un browserView
sobre otro BrowserView
adjunto a win
. Lanza un error si browserView
no está adjunto a win
.
Note The
BrowserView
class is deprecated, and replaced by the newWebContentsView
class.
win.getBrowserViews()
Experimental Obsoleto
Returns BrowserView[]
- a sorted by z-index array of all BrowserViews that have been attached with addBrowserView
or setBrowserView
. The top-most BrowserView is the last element of the array.
Note The
BrowserView
class is deprecated, and replaced by the newWebContentsView
class.
win.setTitleBarOverlay(options)
Windows Linux
On a window with Window Controls Overlay already enabled, this method updates the style of the title bar overlay.
On Linux, the symbolColor
is automatically calculated to have minimum accessible contrast to the color
if not explicitly set.