Cheng Zhao
commit
0839915538
56 changed files with 2303 additions and 602 deletions
|
|
@ -18,9 +18,6 @@ win.show();
|
|||
You can also create a window without chrome by using
|
||||
[Frameless Window](frameless-window.md) API.
|
||||
|
||||
Security strategy of web pages showed by `BrowserWindow` is a bit different from
|
||||
normal browsers, see [Web Security](web-security.md) for more.
|
||||
|
||||
## Class: BrowserWindow
|
||||
|
||||
`BrowserWindow` is an
|
||||
|
|
@ -54,9 +51,8 @@ normal browsers, see [Web Security](web-security.md) for more.
|
|||
* `show` Boolean - Whether window should be shown when created
|
||||
* `frame` Boolean - Specify `false` to create a
|
||||
[Frameless Window](frameless-window.md)
|
||||
* `node-integration` String - Default value is `except-iframe`, can also be
|
||||
`all`, `manual-enable-iframe` or `disable`, see
|
||||
[Web Security](web-security.md) for more informations.
|
||||
* `node-integration` Boolean - Whether node integration is enabled, default
|
||||
is `true`
|
||||
* `accept-first-mouse` Boolean - Whether the web view accepts a single
|
||||
mouse-down event that simultaneously activates the window
|
||||
* `auto-hide-menu-bar` Boolean - Auto hide the menu bar unless the `Alt`
|
||||
|
|
@ -512,14 +508,19 @@ A `WebContents` is responsible for rendering and controlling a web page.
|
|||
`WebContents` is an
|
||||
[EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
|
||||
|
||||
### Event: 'crashed'
|
||||
|
||||
Emitted when the renderer process is crashed.
|
||||
|
||||
### Event: 'did-finish-load'
|
||||
|
||||
Emitted when the navigation is done, i.e. the spinner of the tab will stop
|
||||
spinning, and the onload event was dispatched.
|
||||
spinning, and the `onload` event was dispatched.
|
||||
|
||||
### Event: 'did-fail-load'
|
||||
|
||||
* `event` Event
|
||||
* `errorCode` Integer
|
||||
* `errorDescription` String
|
||||
|
||||
This event is like `did-finish-load`, but emitted when the load failed or was
|
||||
cancelled, e.g. `window.stop()` is invoked.
|
||||
|
||||
### Event: 'did-frame-finish-load'
|
||||
|
||||
|
|
@ -530,8 +531,29 @@ Emitted when a frame has done navigation.
|
|||
|
||||
### Event: 'did-start-loading'
|
||||
|
||||
Corresponds to the points in time when the spinner of the tab starts spinning.
|
||||
|
||||
### Event: 'did-stop-loading'
|
||||
|
||||
Corresponds to the points in time when the spinner of the tab stops spinning.
|
||||
|
||||
### Event: 'did-get-redirect-request'
|
||||
|
||||
* `event` Event
|
||||
* `oldUrl` String
|
||||
* `newUrl` String
|
||||
* `isMainFrame` Boolean
|
||||
|
||||
Emitted when a redirect was received while requesting a resource.
|
||||
|
||||
### Event: 'crashed'
|
||||
|
||||
Emitted when the renderer process is crashed.
|
||||
|
||||
### Event: 'destroyed'
|
||||
|
||||
Emitted when the WebContents is destroyed.
|
||||
|
||||
### WebContents.loadUrl(url)
|
||||
|
||||
* `url` URL
|
||||
|
|
@ -602,10 +624,22 @@ Navigates to the specified absolute index.
|
|||
|
||||
Navigates to the specified offset from the "current entry".
|
||||
|
||||
### WebContents.IsCrashed()
|
||||
### WebContents.isCrashed()
|
||||
|
||||
Whether the renderer process has crashed.
|
||||
|
||||
### WebContents.setUserAgent(userAgent)
|
||||
|
||||
* `userAgent` String
|
||||
|
||||
Overrides the user agent for this page.
|
||||
|
||||
### WebContents.insertCSS(css)
|
||||
|
||||
* `css` String
|
||||
|
||||
Injects CSS into this page.
|
||||
|
||||
### WebContents.executeJavaScript(code)
|
||||
|
||||
* `code` String
|
||||
|
|
|
|||
30
docs/api/file-object.md
Normal file
30
docs/api/file-object.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# `File` object
|
||||
|
||||
The DOM's File interface provides abstraction around native files, in order to
|
||||
let users work on native files directly with HTML5 file API, atom-shell has
|
||||
added a `path` attribute to `File` interface which exposes the file's real path
|
||||
on filesystem.
|
||||
|
||||
Example on getting real path of a dragged file:
|
||||
|
||||
```html
|
||||
<div id="holder">
|
||||
Drag your file here
|
||||
</div>
|
||||
|
||||
<script>
|
||||
var holder = document.getElementById('holder');
|
||||
holder.ondragover = function () {
|
||||
return false;
|
||||
};
|
||||
holder.ondragleave = holder.ondragend = function () {
|
||||
return false;
|
||||
};
|
||||
holder.ondrop = function (e) {
|
||||
e.preventDefault();
|
||||
var file = e.dataTransfer.files[0];
|
||||
console.log('File you dragged here is', file.path);
|
||||
return false;
|
||||
};
|
||||
</script>
|
||||
```
|
||||
|
|
@ -1,26 +1,26 @@
|
|||
# web-view
|
||||
# web-frame
|
||||
|
||||
The `web-view` module can custom the rendering of current web page.
|
||||
The `web-frame` module can custom the rendering of current web page.
|
||||
|
||||
An example of zooming current page to 200%.
|
||||
|
||||
```javascript
|
||||
var webView = require('web-view');
|
||||
webView.setZoomFactor(2);
|
||||
var webFrame = require('web-frame');
|
||||
webFrame.setZoomFactor(2);
|
||||
```
|
||||
|
||||
## webView.setZoomFactor(factor)
|
||||
## webFrame.setZoomFactor(factor)
|
||||
|
||||
* `factor` Number - Zoom factor
|
||||
|
||||
Changes the zoom factor to the specified factor, zoom factor is
|
||||
zoom percent / 100, so 300% = 3.0.
|
||||
|
||||
## webView.getZoomFactor()
|
||||
## webFrame.getZoomFactor()
|
||||
|
||||
Returns the current zoom factor.
|
||||
|
||||
## webView.setZoomLevel(level)
|
||||
## webFrame.setZoomLevel(level)
|
||||
|
||||
* `level` Number - Zoom level
|
||||
|
||||
|
|
@ -28,6 +28,6 @@ Changes the zoom level to the specified level, 0 is "original size", and each
|
|||
increment above or below represents zooming 20% larger or smaller to default
|
||||
limits of 300% and 50% of original size, respectively.
|
||||
|
||||
## webView.getZoomLevel()
|
||||
## webFrame.getZoomLevel()
|
||||
|
||||
Returns the current zoom level.
|
||||
|
|
@ -1,62 +0,0 @@
|
|||
# Web Security
|
||||
|
||||
Because atom-shell has added node integration to normal web pages, there are
|
||||
some security adjustments that made atom-shell both more safe and more
|
||||
convenient.
|
||||
|
||||
## Overriding `X-Frame-Options` header
|
||||
|
||||
May websites (including Google and Youtube) use the
|
||||
[X-Frame-Options][x-frame-options] header to disable access to their websites
|
||||
in `iframe`s. In atom-shell you can add a `disable-x-frame-options` string in
|
||||
the `iframe`'s name to disable this:
|
||||
|
||||
```html
|
||||
<!-- Refused to display -->
|
||||
<iframe name="google" src="https://google.com"></iframe>
|
||||
<!-- Loads as expected -->
|
||||
<iframe name="google-disable-x-frame-options" src="https://google.com"></iframe>
|
||||
```
|
||||
|
||||
## Frames are sandboxed by default
|
||||
|
||||
In normal browsers, `iframe`s are not sandboxed by default, which means a remote
|
||||
page in `iframe` can easily access its parent's JavaScript context.
|
||||
|
||||
In atom-shell because the parent frame may have the power to access native
|
||||
resources, this could cause security problems. In order to fix it, `iframe`s
|
||||
in atom-shell are sandboxed with all permissions except the `allow-same-origin`
|
||||
by default.
|
||||
|
||||
If you want to enable things like `parent.window.process.exit()` in `iframe`s,
|
||||
you need to explicitly add `allow-same-origin` to the `sandbox` attribute, or
|
||||
just set `sandbox` to `none`:
|
||||
|
||||
```html
|
||||
<iframe sandbox="none" src="https://github.com"></iframe>
|
||||
```
|
||||
|
||||
## Node integration in frames
|
||||
|
||||
The `node-integration` option of [BrowserWindow](browser-window.md) controls
|
||||
whether node integration is enabled in web page and its `iframe`s.
|
||||
|
||||
By default the `node-integration` option is `except-iframe`, which means node
|
||||
integration is disabled in all `iframe`s. You can also set it to `all`, with
|
||||
which node integration is available to the main page and all its `iframe`s, or
|
||||
`manual-enable-iframe`, which is like `except-iframe`, but enables `iframe`s
|
||||
whose name contains string `enable-node-integration`. And setting to `disable`
|
||||
would disable the node integration in both the main page and its `iframe`s.
|
||||
|
||||
An example of enable node integration in `iframe` with `node-integration` set to
|
||||
`manual-enable-iframe`:
|
||||
|
||||
```html
|
||||
<!-- iframe with node integration enabled -->
|
||||
<iframe name="gh-enable-node-integration" src="https://github.com"></iframe>
|
||||
|
||||
<!-- iframe with node integration disabled -->
|
||||
<iframe src="http://jandan.net"></iframe>
|
||||
```
|
||||
|
||||
[x-frame-options]: https://developer.mozilla.org/en-US/docs/Web/HTTP/X-Frame-Options
|
||||
271
docs/api/web-view-tag.md
Normal file
271
docs/api/web-view-tag.md
Normal file
|
|
@ -0,0 +1,271 @@
|
|||
# `<webview>` tag
|
||||
|
||||
Use the `webview` tag to embed 'guest' content (such as web pages) in your
|
||||
atom-shell app. The guest content is contained within the `webview` container;
|
||||
an embedder page within your app controls how the guest content is laid out and
|
||||
rendered.
|
||||
|
||||
Different from the `iframe`, the `webview` runs in a separate process than your
|
||||
app; it doesn't have the same permissions as your web page and all interactions
|
||||
between your app and embedded content will be asynchronous. This keeps your app
|
||||
safe from the embedded content.
|
||||
|
||||
## Example
|
||||
|
||||
To embed a web page in your app, add the `webview` tag to your app's embedder
|
||||
page (this is the app page that will display the guest content). In its simplest
|
||||
form, the `webview` tag includes the `src` of the web page and css styles that
|
||||
control the appearance of the `webview` container:
|
||||
|
||||
```html
|
||||
<webview id="foo" src="https://www.github.com/" style="width:640px; height:480px"></webview>
|
||||
```
|
||||
|
||||
If you want to control the guest content in any way, you can write JavaScript
|
||||
that listens for `webview` events and responds to those events using the
|
||||
`webview` methods. Here's sample code with two event listeners: one that listens
|
||||
for the web page to start loading, the other for the web page to stop loading,
|
||||
and displays a "loading..." message during the load time:
|
||||
|
||||
```html
|
||||
<script>
|
||||
onload = function() {
|
||||
var webview = document.getElementById("foo");
|
||||
var indicator = document.querySelector(".indicator");
|
||||
|
||||
var loadstart = function() {
|
||||
indicator.innerText = "loading...";
|
||||
}
|
||||
var loadstop = function() {
|
||||
indicator.innerText = "";
|
||||
}
|
||||
webview.addEventListener("did-start-loading", loadstart);
|
||||
webview.addEventListener("id-stop-loading", loadstop);
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
## Tag attributes
|
||||
|
||||
### src
|
||||
|
||||
```html
|
||||
<webview src="http://www.google.com/"></webview>
|
||||
```
|
||||
|
||||
Returns the visible URL. Writing to this attribute initiates top-level
|
||||
navigation.
|
||||
|
||||
Assigning `src` its own value will reload the current page.
|
||||
|
||||
The `src` attribute can also accept data URLs, such as
|
||||
`data:text/plain,Hello, world!`.
|
||||
|
||||
### autosize
|
||||
|
||||
```html
|
||||
<webview src="http://www.google.com/" autosize="on" minwidth="576" minheight="432"></webview>
|
||||
```
|
||||
|
||||
If "on", the `webview` will container will automatically resize within the
|
||||
bounds specified by the attributes `minwidth`, `minheight`, `maxwidth`, and
|
||||
`maxheight`. These contraints do not impact the `webview` UNLESS `autosize` is
|
||||
enabled. When `autosize` is enabled, the `webview` container size cannot be less
|
||||
than the minimum values or greater than the maximum.
|
||||
|
||||
### nodeintegration
|
||||
|
||||
```html
|
||||
<webview src="http://www.google.com/" nodeintegration></webview>
|
||||
```
|
||||
|
||||
If "on", the guest page in `webview` will have node integration and can use node
|
||||
APIs like `require` and `process` to access low level system resources.
|
||||
|
||||
## Methods
|
||||
|
||||
### `<webview>`.getUrl()
|
||||
|
||||
Returns URL of guest page.
|
||||
|
||||
### `<webview>`.getTitle()
|
||||
|
||||
Returns the title of guest page.
|
||||
|
||||
### `<webview>`.isLoading()
|
||||
|
||||
Returns whether guest page is still loading resources.
|
||||
|
||||
### `<webview>`.isWaitingForResponse()
|
||||
|
||||
Returns whether guest page is waiting for a first-response for the main resource
|
||||
of the page.
|
||||
|
||||
### `<webview>`.stop()
|
||||
|
||||
Stops any pending navigation.
|
||||
|
||||
### `<webview>`.reload()
|
||||
|
||||
Reloads guest page.
|
||||
|
||||
### `<webview>`.reloadIgnoringCache()
|
||||
|
||||
Reloads guest page and ignores cache.
|
||||
|
||||
### `<webview>`.canGoBack()
|
||||
|
||||
Returns whether guest page can go back.
|
||||
|
||||
### `<webview>`.canGoForward()
|
||||
|
||||
Returns whether guest page can go forward.
|
||||
|
||||
### `<webview>`.canGoToOffset(offset)
|
||||
|
||||
* `offset` Integer
|
||||
|
||||
Returns whether guest page can go to `offset`.
|
||||
|
||||
### `<webview>`.goBack()
|
||||
|
||||
Makes guest page go back.
|
||||
|
||||
### `<webview>`.goForward()
|
||||
|
||||
Makes guest page go forward.
|
||||
|
||||
### `<webview>`.goToIndex(index)
|
||||
|
||||
* `index` Integer
|
||||
|
||||
Navigates to the specified absolute index.
|
||||
|
||||
### `<webview>`.goToOffset(offset)
|
||||
|
||||
* `offset` Integer
|
||||
|
||||
Navigates to the specified offset from the "current entry".
|
||||
|
||||
### `<webview>`.isCrashed()
|
||||
|
||||
Whether the renderer process has crashed.
|
||||
|
||||
### `<webview>`.setUserAgent(userAgent)
|
||||
|
||||
* `userAgent` String
|
||||
|
||||
Overrides the user agent for guest page.
|
||||
|
||||
### `<webview>`.insertCSS(css)
|
||||
|
||||
* `css` String
|
||||
|
||||
Injects CSS into guest page.
|
||||
|
||||
### `<webview>`.executeJavaScript(code)
|
||||
|
||||
* `code` String
|
||||
|
||||
Evaluate `code` in guest page.
|
||||
|
||||
### `<webview>`.send(channel[, args...])
|
||||
|
||||
* `channel` String
|
||||
|
||||
Send `args..` to guest page via `channel` in asynchronous message, the guest
|
||||
page can handle it by listening to the `channel` event of `ipc` module.
|
||||
|
||||
See [WebContents.send](browser-window.md#webcontentssendchannel-args) for
|
||||
examples.
|
||||
|
||||
## DOM events
|
||||
|
||||
### did-finish-load
|
||||
|
||||
Fired when the navigation is done, i.e. the spinner of the tab will stop
|
||||
spinning, and the `onload` event was dispatched.
|
||||
|
||||
### did-fail-load
|
||||
|
||||
* `errorCode` Integer
|
||||
* `errorDescription` String
|
||||
|
||||
This event is like `did-finish-load`, but fired when the load failed or was
|
||||
cancelled, e.g. `window.stop()` is invoked.
|
||||
|
||||
### did-frame-finish-load
|
||||
|
||||
* `isMainFrame` Boolean
|
||||
|
||||
Fired when a frame has done navigation.
|
||||
|
||||
### did-start-loading
|
||||
|
||||
Corresponds to the points in time when the spinner of the tab starts spinning.
|
||||
|
||||
### did-stop-loading
|
||||
|
||||
Corresponds to the points in time when the spinner of the tab stops spinning.
|
||||
|
||||
### did-get-redirect-request
|
||||
|
||||
* `oldUrl` String
|
||||
* `newUrl` String
|
||||
* `isMainFrame` Boolean
|
||||
|
||||
Fired when a redirect was received while requesting a resource.
|
||||
|
||||
### console-message
|
||||
|
||||
* `level` Integer
|
||||
* `message` String
|
||||
* `line` Integer
|
||||
* `sourceId` String
|
||||
|
||||
Fired when the guest window logs a console message.
|
||||
|
||||
The following example code forwards all log messages to the embedder's console
|
||||
without regard for log level or other properties.
|
||||
|
||||
```javascript
|
||||
webview.addEventListener('console-message', function(e) {
|
||||
console.log('Guest page logged a message: ', e.message);
|
||||
});
|
||||
```
|
||||
|
||||
### new-window
|
||||
|
||||
* `url` String
|
||||
* `partitionId` String
|
||||
|
||||
Fired when the guest page attempts to open a new browser window.
|
||||
|
||||
The following example code opens the new url in system's default browser.
|
||||
|
||||
```javascript
|
||||
webview.addEventListener('new-window', function(e) {
|
||||
require('shell').openExternal(e.url);
|
||||
});
|
||||
```
|
||||
|
||||
### close
|
||||
|
||||
Fired when the guest window attempts to close itself.
|
||||
|
||||
The following example code navigates the `webview` to `about:blank` when the
|
||||
guest attempts to close itself.
|
||||
|
||||
```javascript
|
||||
webview.addEventListener('close', function() {
|
||||
webview.src = 'about:blank';
|
||||
});
|
||||
```
|
||||
|
||||
### crashed
|
||||
|
||||
Fired when the renderer process is crashed.
|
||||
|
||||
### destroyed
|
||||
|
||||
Fired when the WebContents is destroyed.
|
||||
Loading…
Add table
Add a link
Reference in a new issue