mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

prepare for retaining "Guides" pages

Browse source
This commit is contained in:
fbukevin 2016-01-28 18:20:39 +08:00
parent 3c9e08faf1
commit 223b440bc8
6 changed files with 507 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

76
docs-translations/zh-TW/tutorial/debugging-main-process.md Normal file
View file

@ -0,0 +1,76 @@
# Debugging the Main Process
The browser window DevTools can only debug the renderer process scripts (i.e.
the web pages). In order to provide a way to debug the scripts from the main
process, Electron has provided the `--debug` and `--debug-brk` switches.
## Command Line Switches
Use the following command line switches to debug Electron's main process:
### `--debug=[port]`
When this switch is used Electron will listen for V8 debugger protocol
messages on `port`. The default `port` is `5858`.
### `--debug-brk=[port]`
Like `--debug` but pauses the script on the first line.
## Use node-inspector for Debugging
__Note:__ Electron doesn't currently work very well
with node-inspector, and the main process will crash if you inspect the
`process` object under node-inspector's console.
### 1. Make sure you have [node-gyp required tools][node-gyp-required-tools] installed
### 2. Install [node-inspector][node-inspector]
```bash
$ npm install node-inspector
```
### 3. Install a patched version of `node-pre-gyp`
```bash
$ npm install git+https://git@github.com/enlight/node-pre-gyp.git#detect-electron-runtime-in-find
```
### 4. Recompile the `node-inspector` `v8` modules for electron (change the target to your electron version number)
```bash
$ node_modules/.bin/node-pre-gyp --target=0.36.2 --runtime=electron --fallback-to-build --directory node_modules/v8-debug/ --dist-url=https://atom.io/download/atom-shell reinstall
$ node_modules/.bin/node-pre-gyp --target=0.36.2 --runtime=electron --fallback-to-build --directory node_modules/v8-profiler/ --dist-url=https://atom.io/download/atom-shell reinstall
```
See also [How to install native modules](how-to-install-native-modules).
### 5. Enable debug mode for Electron
You can either start Electron with a debug flag like:
```bash
$ electron --debug=5858 your/app
```
or, to pause your script on the first line:
```bash
$ electron --debug-brk=5858 your/app
```
### 6. Start the [node-inspector][node-inspector] server using electron
```bash
$ ELECTRON_RUN_AS_NODE=true path/to/electron.exe node_modules/node-inspector/bin/inspector.js
```
### 7. Load the debugger UI
Open http://127.0.0.1:8080/debug?ws=127.0.0.1:8080&port=5858 in the Chrome browser. You may have to click pause if starting with debug-brk to see the entry line.
[node-inspector]: https://github.com/node-inspector/node-inspector
[node-gyp-required-tools]: https://github.com/nodejs/node-gyp#installation
[how-to-install-native-modules]: using-native-node-modules.md#how-to-install-native-modules

62
docs-translations/zh-TW/tutorial/devtools-extension.md Normal file
View file

@ -0,0 +1,62 @@
# DevTools Extension
To make debugging easier, Electron has basic support for the
[Chrome DevTools Extension][devtools-extension].
For most DevTools extensions you can simply download the source code and use
the `BrowserWindow.addDevToolsExtension` API to load them. The loaded extensions
will be remembered so you don't need to call the API every time when creating
a window.
** NOTE: React DevTools does not work, follow the issue here https://github.com/atom/electron/issues/915 **
For example, to use the [React DevTools Extension](https://github.com/facebook/react-devtools)
, first you need to download its source code:
```bash
$ cd /some-directory
$ git clone --recursive https://github.com/facebook/react-devtools.git
```
Follow the instructions in [`react-devtools/shells/chrome/Readme.md`](https://github.com/facebook/react-devtools/blob/master/shells/chrome/Readme.md) to build the extension.
Then you can load the extension in Electron by opening DevTools in any window,
and running the following code in the DevTools console:
```javascript
const BrowserWindow = require('electron').remote.BrowserWindow;
BrowserWindow.addDevToolsExtension('/some-directory/react-devtools/shells/chrome');
```
To unload the extension, you can call the `BrowserWindow.removeDevToolsExtension`
API with its name and it will not load the next time you open the DevTools:
```javascript
BrowserWindow.removeDevToolsExtension('React Developer Tools');
```
## Format of DevTools Extension
Ideally all DevTools extensions written for the Chrome browser can be loaded by
Electron, but they have to be in a plain directory. For those packaged with
`crx` extensions, there is no way for Electron to load them unless you find a
way to extract them into a directory.
## Background Pages
Currently Electron doesn't support the background pages feature in Chrome
extensions, so some DevTools extensions that rely on this feature may
not work in Electron.
## `chrome.*` APIs
Some Chrome extensions may use `chrome.*` APIs for features and while there has
been some effort to implement those APIs in Electron, not all have been
implemented.
Given that not all `chrome.*` APIs are implemented if the DevTools extension is
using APIs other than `chrome.devtools.*`, the extension is very likely not to
work. You can report failing extensions in the issue tracker so that we can add
support for those APIs.
[devtools-extension]: https://developer.chrome.com/extensions/devtools

120
docs-translations/zh-TW/tutorial/mac-app-store-submission-guide.md Normal file
View file

@ -0,0 +1,120 @@
# Mac App Store Submission Guide
Since v0.34.0, Electron allows submitting packaged apps to the Mac App Store
(MAS). This guide provides information on: how to submit your app and the
limitations of the MAS build.
__Note:__ Submitting an app to Mac App Store requires enrolling [Apple Developer
Program][developer-program], which costs money.
## How to Submit Your App
The following steps introduce a simple way to submit your app to Mac App Store.
However, these steps do not ensure your app will be approved by Apple; you
still need to read Apple's [Submitting Your App][submitting-your-app] guide on
how to meet the Mac App Store requirements.
### Get Certificate
To submit your app to the Mac App Store, you first must get a certificate from
Apple. You can follow these [existing guides][nwjs-guide] on web.
### Sign Your App
After getting the certificate from Apple, you can package your app by following
[Application Distribution](application-distribution.md), and then proceed to
signing your app. This step is basically the same with other programs, but the
key is to sign every dependency of Electron one by one.
First, you need to prepare two entitlements files.
`child.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.app-sandbox</key>
<true/>
<key>com.apple.security.inherit</key>
<true/>
</dict>
</plist>
```
`parent.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.app-sandbox</key>
<true/>
</dict>
</plist>
```
And then sign your app with the following script:
```bash
#!/bin/bash
# Name of your app.
APP="YourApp"
# The path of you app to sign.
APP_PATH="/path/to/YouApp.app"
# The path to the location you want to put the signed package.
RESULT_PATH="~/Desktop/$APP.pkg"
# The name of certificates you requested.
APP_KEY="3rd Party Mac Developer Application: Company Name (APPIDENTITY)"
INSTALLER_KEY="3rd Party Mac Developer Installer: Company Name (APPIDENTITY)"
FRAMEWORKS_PATH="$APP_PATH/Contents/Frameworks"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Electron Framework.framework/Libraries/libnode.dylib"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Electron Framework.framework/Electron Framework"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Electron Framework.framework/"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper.app/"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper EH.app/"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper NP.app/"
codesign -fs "$APP_KEY" --entitlements parent.plist "$APP_PATH"
productbuild --component "$APP_PATH" /Applications --sign "$INSTALLER_KEY" "$RESULT_PATH"
```
If you are new to app sandboxing under OS X, you should also read through
Apple's [Enabling App Sandbox][enable-app-sandbox] to have a basic idea, then
add keys for the permissions needed by your app to the entitlements files.
### Upload Your App and Submit for Review
After signing your app, you can use Application Loader to upload it to iTunes
Connect for processing, making sure you have [created a record][create-record]
before uploading. Then you can [submit your app for review][submit-for-review].
## Limitations of MAS Build
In order to satisfy all requirements for app sandboxing, the following modules
have been disabled in the MAS build:
* `crash-reporter`
* `auto-updater`
and the following behaviors have been changed:
* Video capture may not work for some machines.
* Certain accessibility features may not work.
* Apps will not be aware of DNS changes.
Also, due to the usage of app sandboxing, the resources which can be accessed by
the app are strictly limited; you can read [App Sandboxing][app-sandboxing] for
more information.
[developer-program]: https://developer.apple.com/support/compare-memberships/
[submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html
[nwjs-guide]: https://github.com/nwjs/nw.js/wiki/Mac-App-Store-%28MAS%29-Submission-Guideline#first-steps
[enable-app-sandbox]: https://developer.apple.com/library/ios/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html
[create-record]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/CreatingiTunesConnectRecord.html
[submit-for-review]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/SubmittingTheApp.html
[app-sandboxing]: https://developer.apple.com/app-sandboxing/

67
docs-translations/zh-TW/tutorial/using-native-node-modules.md Normal file
View file

@ -0,0 +1,67 @@
# Using Native Node Modules
The native Node modules are supported by Electron, but since Electron is
using a different V8 version from official Node, you have to manually specify
the location of Electron's headers when building native modules.
## Native Node Module Compatibility
Native modules might break when Node starts using a new version of V8.
To make sure the module you're interested in will work with Electron, you should
check if it supports the internal Node version used by Electron.
You can check what version of Node is used in Electron by looking it up in
the [releases](https://github.com/atom/electron/releases) page or by using
`process.version` (see [Quick Start](https://github.com/atom/electron/blob/master/docs/tutorial/quick-start.md)
for example).
Consider using [NAN](https://github.com/nodejs/nan/) for your own modules, since
it makes it easier to support multiple versions of Node. It's also helpful for
porting old modules to newer versions of Node so they can work with Electron.
## How to Install Native Modules
Three ways to install native modules:
### The Easy Way
The most straightforward way to rebuild native modules is via the
[`electron-rebuild`](https://github.com/paulcbetts/electron-rebuild) package,
which handles the manual steps of downloading headers and building native modules:
```sh
npm install --save-dev electron-rebuild
# Every time you run "npm install", run this
./node_modules/.bin/electron-rebuild
# On Windows if you have trouble, try:
.\node_modules\.bin\electron-rebuild.cmd
```
### The npm Way
You can also use `npm` to install modules. The steps are exactly the same with
Node modules, except that you need to setup some environment variables:
```bash
export npm_config_disturl=https://atom.io/download/atom-shell
export npm_config_target=0.33.1
export npm_config_arch=x64
export npm_config_runtime=electron
HOME=~/.electron-gyp npm install module-name
```
### The node-gyp Way
To build Node modules with headers of Electron, you need to tell `node-gyp`
where to download headers and which version to use:
```bash
$ cd /path-to-module/
$ HOME=~/.electron-gyp node-gyp rebuild --target=0.29.1 --arch=x64 --dist-url=https://atom.io/download/atom-shell
```
The `HOME=~/.electron-gyp` changes where to find development headers. The
`--target=0.29.1` is version of Electron. The `--dist-url=...` specifies
where to download the headers. The `--arch=x64` says the module is built for
64bit system.

50
docs-translations/zh-TW/tutorial/using-pepper-flash-plugin.md Normal file
View file

@ -0,0 +1,50 @@
# Using Pepper Flash Plugin
Electron now supports the Pepper Flash plugin. To use the Pepper Flash plugin in
Electron, you should manually specify the location of the Pepper Flash plugin
and then enable it in your application.
## Prepare a Copy of Flash Plugin
On OS X and Linux, the details of the Pepper Flash plugin can be found by
navigating to `chrome://plugins` in the Chrome browser. Its location and version
are useful for Electron's Pepper Flash support. You can also copy it to another
location.
## Add Electron Switch
You can directly add `--ppapi-flash-path` and `ppapi-flash-version` to the
Electron command line or by using the `app.commandLine.appendSwitch` method
before the app ready event. Also, add the `plugins` switch of `browser-window`.
For example:
```javascript
// Specify flash path.
// On Windows, it might be /path/to/pepflashplayer.dll
// On OS X, /path/to/PepperFlashPlayer.plugin
// On Linux, /path/to/libpepflashplayer.so
app.commandLine.appendSwitch('ppapi-flash-path', '/path/to/libpepflashplayer.so');
// Specify flash version, for example, v17.0.0.169
app.commandLine.appendSwitch('ppapi-flash-version', '17.0.0.169');
app.on('ready', function() {
mainWindow = new BrowserWindow({
'width': 800,
'height': 600,
'web-preferences': {
'plugins': true
}
});
mainWindow.loadURL('file://' + __dirname + '/index.html');
// Something else
});
```
## Enable Flash Plugin in a `<webview>` Tag
Add `plugins` attribute to `<webview>` tag.
```html
<webview src="http://www.adobe.com/software/flash/about/" plugins></webview>
```

132
docs-translations/zh-TW/tutorial/using-selenium-and-webdriver.md Normal file
View file

@ -0,0 +1,132 @@
# Using Selenium and WebDriver
From [ChromeDriver - WebDriver for Chrome][chrome-driver]:
> WebDriver is an open source tool for automated testing of web apps across many
> browsers. It provides capabilities for navigating to web pages, user input,
> JavaScript execution, and more. ChromeDriver is a standalone server which
> implements WebDriver's wire protocol for Chromium. It is being developed by
> members of the Chromium and WebDriver teams.
In order to use `chromedriver` with Electron you have to tell it where to
find Electron and make it think Electron is the Chrome browser.
## Setting up with WebDriverJs
[WebDriverJs](https://code.google.com/p/selenium/wiki/WebDriverJs) provides
a Node package for testing with web driver, we will use it as an example.
### 1. Start ChromeDriver
First you need to download the `chromedriver` binary, and run it:
```bash
$ ./chromedriver
Starting ChromeDriver (v2.10.291558) on port 9515
Only local connections are allowed.
```
Remember the port number `9515`, which will be used later
### 2. Install WebDriverJS
```bash
$ npm install selenium-webdriver
```
### 3. Connect to ChromeDriver
The usage of `selenium-webdriver` with Electron is basically the same with
upstream, except that you have to manually specify how to connect chrome driver
and where to find Electron's binary:
```javascript
const webdriver = require('selenium-webdriver');
var driver = new webdriver.Builder()
// The "9515" is the port opened by chrome driver.
.usingServer('http://localhost:9515')
.withCapabilities({
chromeOptions: {
// Here is the path to your Electron binary.
binary: '/Path-to-Your-App.app/Contents/MacOS/Atom',
}
})
.forBrowser('electron')
.build();
driver.get('http://www.google.com');
driver.findElement(webdriver.By.name('q')).sendKeys('webdriver');
driver.findElement(webdriver.By.name('btnG')).click();
driver.wait(function() {
return driver.getTitle().then(function(title) {
return title === 'webdriver - Google Search';
});
}, 1000);
driver.quit();
```
## Setting up with WebdriverIO
[WebdriverIO](http://webdriver.io/) provides a Node package for testing with web
driver.
### 1. Start ChromeDriver
First you need to download the `chromedriver` binary, and run it:
```bash
$ chromedriver --url-base=wd/hub --port=9515
Starting ChromeDriver (v2.10.291558) on port 9515
Only local connections are allowed.
```
Remember the port number `9515`, which will be used later
### 2. Install WebdriverIO
```bash
$ npm install webdriverio
```
### 3. Connect to chrome driver
```javascript
const webdriverio = require('webdriverio');
var options = {
host: "localhost", // Use localhost as chrome driver server
port: 9515, // "9515" is the port opened by chrome driver.
desiredCapabilities: {
browserName: 'chrome',
chromeOptions: {
binary: '/Path-to-Your-App/electron', // Path to your Electron binary.
args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/
}
}
};
var client = webdriverio.remote(options);
client
.init()
.url('http://google.com')
.setValue('#q', 'webdriverio')
.click('#btnG')
.getTitle().then(function(title) {
console.log('Title was: ' + title);
})
.end();
```
## Workflow
To test your application without rebuilding Electron, simply
[place](https://github.com/atom/electron/blob/master/docs/tutorial/application-distribution.md)
your app source into Electron's resource directory.
Alternatively, pass an argument to run with your electron binary that points to
your app's folder. This eliminates the need to copy-paste your app into
Electron's resource directory.
[chrome-driver]: https://sites.google.com/a/chromium.org/chromedriver/