|
|
@@ -6,16 +6,15 @@ untrusted content within a renderer. Windows can be created from the renderer in
|
|
|
* clicking on links or submitting forms adorned with `target=_blank`
|
|
|
* JavaScript calling `window.open()`
|
|
|
|
|
|
-In non-sandboxed renderers, or when `nativeWindowOpen` is false (the default), this results in the creation of a
|
|
|
-[`BrowserWindowProxy`](browser-window-proxy.md), a light wrapper around
|
|
|
-`BrowserWindow`.
|
|
|
+For same-origin content, the new window is created within the same process,
|
|
|
+enabling the parent to access the child window directly. This can be very
|
|
|
+useful for app sub-windows that act as preference panels, or similar, as the
|
|
|
+parent can render to the sub-window directly, as if it were a `div` in the
|
|
|
+parent. This is the same behavior as in the browser.
|
|
|
|
|
|
-However, when the `sandbox` (or directly, `nativeWindowOpen`) option is set, a
|
|
|
-`Window` instance is created, as you'd expect in the browser. For same-origin
|
|
|
-content, the new window is created within the same process, enabling the parent
|
|
|
-to access the child window directly. This can be very useful for app sub-windows that act
|
|
|
-as preference panels, or similar, as the parent can render to the sub-window
|
|
|
-directly, as if it were a `div` in the parent.
|
|
|
+When `nativeWindowOpen` is set to false, `window.open` instead results in the
|
|
|
+creation of a [`BrowserWindowProxy`](browser-window-proxy.md), a light wrapper
|
|
|
+around `BrowserWindow`.
|
|
|
|
|
|
Electron pairs this native Chrome `Window` with a BrowserWindow under the hood.
|
|
|
You can take advantage of all the customization available when creating a
|
|
|
@@ -69,49 +68,18 @@ window.open('https://github.com', '_blank', 'top=500,left=200,frame=false,nodeIn
|
|
|
|
|
|
To customize or cancel the creation of the window, you can optionally set an
|
|
|
override handler with `webContents.setWindowOpenHandler()` from the main
|
|
|
-process. Returning `false` cancels the window, while returning an object sets
|
|
|
-the `BrowserWindowConstructorOptions` used when creating the window. Note that
|
|
|
-this is more powerful than passing options through the feature string, as the
|
|
|
-renderer has more limited privileges in deciding security preferences than the
|
|
|
-main process.
|
|
|
-
|
|
|
-### `BrowserWindowProxy` example
|
|
|
-
|
|
|
-```javascript
|
|
|
-
|
|
|
-// main.js
|
|
|
-const mainWindow = new BrowserWindow()
|
|
|
-
|
|
|
-mainWindow.webContents.setWindowOpenHandler(({ url }) => {
|
|
|
- if (url.startsWith('https://github.com/')) {
|
|
|
- return { action: 'allow' }
|
|
|
- }
|
|
|
- return { action: 'deny' }
|
|
|
-})
|
|
|
-
|
|
|
-mainWindow.webContents.on('did-create-window', (childWindow) => {
|
|
|
- // For example...
|
|
|
- childWindow.webContents.on('will-navigate', (e) => {
|
|
|
- e.preventDefault()
|
|
|
- })
|
|
|
-})
|
|
|
-```
|
|
|
-
|
|
|
-```javascript
|
|
|
-// renderer.js
|
|
|
-const windowProxy = window.open('https://github.com/', null, 'minimizable=false')
|
|
|
-windowProxy.postMessage('hi', '*')
|
|
|
-```
|
|
|
+process. Returning `{ action: 'deny' }` cancels the window. Returning `{
|
|
|
+action: 'allow', overrideBrowserWindowOptions: { ... } }` will allow opening
|
|
|
+the window and setting the `BrowserWindowConstructorOptions` to be used when
|
|
|
+creating the window. Note that this is more powerful than passing options
|
|
|
+through the feature string, as the renderer has more limited privileges in
|
|
|
+deciding security preferences than the main process.
|
|
|
|
|
|
### Native `Window` example
|
|
|
|
|
|
```javascript
|
|
|
// main.js
|
|
|
-const mainWindow = new BrowserWindow({
|
|
|
- webPreferences: {
|
|
|
- nativeWindowOpen: true
|
|
|
- }
|
|
|
-})
|
|
|
+const mainWindow = new BrowserWindow()
|
|
|
|
|
|
// In this example, only windows with the `about:blank` url will be created.
|
|
|
// All other urls will be blocked.
|
|
|
@@ -135,3 +103,33 @@ mainWindow.webContents.setWindowOpenHandler(({ url }) => {
|
|
|
const childWindow = window.open('', 'modal')
|
|
|
childWindow.document.write('<h1>Hello</h1>')
|
|
|
```
|
|
|
+
|
|
|
+### `BrowserWindowProxy` example
|
|
|
+
|
|
|
+```javascript
|
|
|
+
|
|
|
+// main.js
|
|
|
+const mainWindow = new BrowserWindow({
|
|
|
+ webPreferences: { nativeWindowOpen: false }
|
|
|
+})
|
|
|
+
|
|
|
+mainWindow.webContents.setWindowOpenHandler(({ url }) => {
|
|
|
+ if (url.startsWith('https://github.com/')) {
|
|
|
+ return { action: 'allow' }
|
|
|
+ }
|
|
|
+ return { action: 'deny' }
|
|
|
+})
|
|
|
+
|
|
|
+mainWindow.webContents.on('did-create-window', (childWindow) => {
|
|
|
+ // For example...
|
|
|
+ childWindow.webContents.on('will-navigate', (e) => {
|
|
|
+ e.preventDefault()
|
|
|
+ })
|
|
|
+})
|
|
|
+```
|
|
|
+
|
|
|
+```javascript
|
|
|
+// renderer.js
|
|
|
+const windowProxy = window.open('https://github.com/', null, 'minimizable=false')
|
|
|
+windowProxy.postMessage('hi', '*')
|
|
|
+```
|
Jeremy Rose